annotate lispref/text.texi @ 48657:81f6fbdaa117

(gud-menu-map): Update for bashdb. (perldb): Change prompt regexp. (gud-bashdb-history, gud-bashdb-massage-args, gud-bashdb-marker-filter) (gud-bashdb-find-file, gud-bashdb-command-name, bashdb): New.
author Richard M. Stallman <rms@gnu.org>
date Wed, 04 Dec 2002 11:56:55 +0000
parents ee41d5989edf
children 55666b1c590b
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.
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/text
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
7 @node Text, Non-ASCII Characters, Markers, Top
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 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
12 buffer. Most examine, insert, or delete text in the current buffer,
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
13 often operating at point or on text adjacent to point. Many are
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
14 interactive. All the functions that change the text provide for undoing
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
15 the changes (@pxref{Undo}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 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
18 buffer positions passed in arguments named @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 These arguments should be either markers (@pxref{Markers}) or numeric
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 character positions (@pxref{Positions}). The order of these arguments
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 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
22 region and @var{end} the beginning. For example, @code{(delete-region 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 10)} and @code{(delete-region 10 1)} are equivalent. An
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @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
25 @var{end} is outside the accessible portion of the buffer. In an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 interactive call, point and the mark are used for these arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 @cindex buffer contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 Throughout this chapter, ``text'' refers to the characters in the
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
30 buffer, together with their properties (when relevant). Keep in mind
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
31 that point is always between two characters, and the cursor appears on
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
32 the character after point.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 * Near Point:: Examining text in the vicinity of point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 * Buffer Contents:: Examining text in a general fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Comparing Text:: Comparing substrings of buffers.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 * Insertion:: Adding new text to a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * Commands for Insertion:: User-level commands to insert text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Deletion:: Removing text from a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * User-Level Deletion:: User-level commands to delete text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 * The Kill Ring:: Where removed text sometimes is saved for later use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 * Undo:: Undoing changes to the text of a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 * Maintaining Undo:: How to enable and disable undo information.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 How to control how much information is kept.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * Filling:: Functions for explicit filling.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
47 * Margins:: How to specify margins for filling commands.
23147
ad9732e88e90 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22267
diff changeset
48 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 * Auto Filling:: How auto-fill mode is implemented to break lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 * Sorting:: Functions for sorting parts of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 * Columns:: Computing horizontal positions, and using them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 * Indentation:: Functions to insert or adjust indentation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 * Case Changes:: Case conversion of parts of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 * Text Properties:: Assigning Lisp property lists to text characters.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 * Substitution:: Replacing a given character wherever it appears.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
56 * Transposition:: Swapping two portions of a buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 * Registers:: How registers are implemented. Accessing the text or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 position stored in a register.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
59 * Base 64:: Conversion to or from base 64 encoding.
39208
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
60 * MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 * Change Hooks:: Supplying functions to be run when text is changed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @node Near Point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @section Examining Text Near Point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 Many functions are provided to look at the characters around point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 Several simple functions are described here. See also @code{looking-at}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 in @ref{Regexp Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
71 @defun char-after &optional position
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 This function returns the character in the current buffer at (i.e.,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 immediately after) position @var{position}. If @var{position} is out of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 range for this purpose, either before the beginning of the buffer, or at
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
75 or beyond the end, then the value is @code{nil}. The default for
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
76 @var{position} is point.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 In the following example, assume that the first character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 buffer is @samp{@@}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 (char-to-string (char-after 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 @result{} "@@"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
89 @defun char-before &optional position
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
90 This function returns the character in the current buffer immediately
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
91 before position @var{position}. If @var{position} is out of range for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
92 this purpose, either before the beginning of the buffer, or at or beyond
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
93 the end, then the value is @code{nil}. The default for
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
94 @var{position} is point.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
95 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
96
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @defun following-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 This function returns the character following point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 buffer. This is similar to @code{(char-after (point))}. However, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 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
101
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 Remember that point is always between characters, and the terminal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 cursor normally appears over the character following point. Therefore,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 the character returned by @code{following-char} is the character the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 cursor is over.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 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
108
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 Gentlemen may cry ``Pea@point{}ce! Peace!,''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 but there is no peace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 (char-to-string (preceding-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @result{} "a"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 (char-to-string (following-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 @result{} "c"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @defun preceding-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 This function returns the character preceding point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 buffer. See above, under @code{following-char}, for an example. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 point is at the beginning of the buffer, @code{preceding-char} returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @defun bobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 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
135 buffer. If narrowing is in effect, this means the beginning of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 accessible portion of the text. See also @code{point-min} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @ref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @defun eobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 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
142 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
143 the text. See also @code{point-max} in @xref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @end defun
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 @defun bolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 This function returns @code{t} if point is at the beginning of a line.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
148 @xref{Text Lines}. The beginning of the buffer (or of its accessible
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
149 portion) always counts as the beginning of a line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @defun eolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 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
154 end of the buffer (or of its accessible portion) is always considered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 the end of a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @node Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @section Examining Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 This section describes two functions that allow a Lisp program to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 convert any portion of the text in the buffer into a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @defun buffer-substring start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 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
166 region defined by positions @var{start} and @var{end} in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 buffer. If the arguments are not positions in the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 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
172 arguments can be given in either order. But most often the smaller
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 argument is written first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
175 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
176 the string along with the characters they belong to. @xref{Text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
177 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
178 their properties are ignored, not copied.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
179
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 (buffer-substring 1 10)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @result{} "This is t"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 (buffer-substring (point-max) 10)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @result{} "he contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
13109
acb0ab49f4e7 Fix name of buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 12775
diff changeset
200 @defun buffer-substring-no-properties start end
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
201 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
202 properties, just the characters themselves. @xref{Text Properties}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
203 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
204
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 @defun buffer-string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
206 This function returns the contents of the entire accessible portion of
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
207 the current buffer as a string. It is equivalent to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
208
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
209 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
210 (buffer-substring (point-min) (point-max))
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
211 @end example
6558
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 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 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 (buffer-string)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @result{} "This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
227 @defun thing-at-point thing
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
228 Return the @var{thing} around or next to point, as a string.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
229
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
230 The argument @var{thing} is a symbol which specifies a kind of syntactic
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
231 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
232 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
233 @code{whitespace}, @code{line}, @code{page}, and others.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
234
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
235 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
236 ---------- Buffer: foo ----------
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
237 Gentlemen may cry ``Pea@point{}ce! Peace!,''
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
238 but there is no peace.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
239 ---------- Buffer: foo ----------
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
240
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
241 (thing-at-point 'word)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
242 @result{} "Peace"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
243 (thing-at-point 'line)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
244 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
245 (thing-at-point 'whitespace)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
246 @result{} nil
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
247 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
248 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
249
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @node Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @section Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @cindex comparing buffer text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 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
255 copying them into strings first.
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 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 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
259 different buffers. The first three arguments specify one substring,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 giving a buffer and two positions within the buffer. The last three
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 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
262 @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
263 current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 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
266 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
267 the result is one plus the index of the first differing characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 within the substrings.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 This function ignores case when comparing characters
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
271 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
272 text properties.
6558
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 Suppose the current buffer contains the text @samp{foobarbar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 haha!rara!}; then in this example the two substrings are @samp{rbar }
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 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
277 at the second character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
280 (compare-buffer-substrings nil 6 11 nil 16 21)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @result{} 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @node Insertion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
286 @section Inserting Text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @cindex insertion of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @cindex text insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
290 @cindex insertion before point
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
291 @cindex before point, insertion
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @dfn{Insertion} means adding new text to a buffer. The inserted text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 goes at point---between the character before point and the character
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
294 after point. Some insertion functions leave point before the inserted
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
295 text, while other functions leave it after. We call the former
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
296 insertion @dfn{after point} and the latter insertion @dfn{before point}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 Insertion relocates markers that point at positions after the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 insertion point, so that they stay with the surrounding text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 (@pxref{Markers}). When a marker points at the place of insertion,
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
301 insertion may or may not relocate the marker, depending on the marker's
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
302 insertion type (@pxref{Marker Insertion Types}). Certain special
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
303 functions such as @code{insert-before-markers} relocate all such markers
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
304 to point after the inserted text, regardless of the markers' insertion
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
305 type.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 Insertion functions signal an error if the current buffer is
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
308 read-only or if they insert within read-only text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
310 These functions copy text characters from strings and buffers along
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
311 with their properties. The inserted characters have exactly the same
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
312 properties as the characters they were copied from. By contrast,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
313 characters specified as separate arguments, not part of a string or
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
314 buffer, inherit their text properties from the neighboring text.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
315
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
316 The insertion functions convert text from unibyte to multibyte in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
317 order to insert in a multibyte buffer, and vice versa---if the text
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
318 comes from a string or from a buffer. However, they do not convert
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
319 unibyte character codes 128 through 255 to multibyte characters, not
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
320 even if the current buffer is a multibyte buffer. @xref{Converting
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
321 Representations}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
322
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @defun insert &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 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
325 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
326 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
327 @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
328 @end defun
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 @defun insert-before-markers &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 This function inserts the strings and/or characters @var{args} into the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 current buffer, at point, moving point forward. An error is signaled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 unless all @var{args} are either strings or characters. The value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 This function is unlike the other insertion functions in that it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 relocates markers initially pointing at the insertion point, to point
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
338 after the inserted text. If an overlay begins the insertion point, the
16934
853f638bbc81 Document how insert-before-markers affects overlays.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
339 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
340 the insertion point, the inserted text falls inside that overlay.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
343 @defun insert-char character &optional count inherit
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 This function inserts @var{count} instances of @var{character} into the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
345 current buffer before point. The argument @var{count} should be a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
346 number (@code{nil} means 1), and @var{character} must be a character.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
347 The value is @code{nil}.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
348
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
349 This function does not convert unibyte character codes 128 through 255
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
350 to multibyte characters, not even if the current buffer is a multibyte
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
351 buffer. @xref{Converting Representations}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
352
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
353 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
354 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
355 insertion point. @xref{Sticky Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @defun insert-buffer-substring from-buffer-or-name &optional start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 This function inserts a portion of buffer @var{from-buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 (which must already exist) into the current buffer before point. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 text inserted is the region from @var{start} and @var{end}. (These
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 arguments default to the beginning and end of the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 that buffer.) This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 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
366 current buffer. We assume that buffer @samp{bar} is initially empty.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 We hold these truths to be self-evident, that all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @end group
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 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 (insert-buffer-substring "foo" 1 20)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 ---------- Buffer: bar ----------
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
380 We hold these truth@point{}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @xref{Sticky Properties}, for other insertion functions that inherit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
387 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
388 Whitespace inserted by indentation functions also inherits text
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
389 properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @node Commands for Insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @section User-Level Insertion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 This section describes higher-level commands for inserting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @deffn Command insert-buffer from-buffer-or-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 This command inserts the entire contents of @var{from-buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 (which must exist) into the current buffer after point. It leaves
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 the mark after the inserted text. The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @deffn Command self-insert-command count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @cindex character insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @cindex self-insertion
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
407 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
408 times, before point, and returns @code{nil}. Most printing characters
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
409 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
410 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
411 it except to install it on a keymap.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 In an interactive call, @var{count} is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
415 This command calls @code{auto-fill-function} whenever that is
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
416 non-@code{nil} and the character inserted is in the table
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
417 @code{auto-fill-chars} (@pxref{Auto Filling}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
420 This command performs abbrev expansion if Abbrev mode is enabled and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 the inserted character does not have word-constituent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
424 This is also responsible for calling @code{blink-paren-function} when
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
425 the inserted character has close parenthesis syntax (@pxref{Blinking}).
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
426
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
427 Do not try substituting your own definition of
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
428 @code{self-insert-command} for the standard one. The editor command
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
429 loop handles this function specially.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @deffn Command newline &optional number-of-newlines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 This command inserts newlines into the current buffer before point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 If @var{number-of-newlines} is supplied, that many newline characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 are inserted.
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 @cindex newline and Auto Fill mode
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
438 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
439 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
440 @var{number-of-newlines} is @code{nil}. Typically what
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
441 @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
442 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
443 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
444 auto-fill if @var{number-of-newlines} is non-@code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
446 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
447 @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
448
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 The value returned is @code{nil}. In an interactive call, @var{count}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @end deffn
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 split-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 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
455 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
456 below where it was before. Whitespace is inserted as needed at the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 beginning of the lower line, using the @code{indent-to} function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @code{split-line} returns the position of point.
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 Programs hardly ever use this function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @defvar overwrite-mode
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
464 This variable controls whether overwrite mode is in effect. The value
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
465 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
466 or @code{nil}. @code{overwrite-mode-textual} specifies textual
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
467 overwrite mode (treats newlines and tabs specially), and
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
468 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
469 newlines and tabs like any other characters).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @node Deletion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
473 @section Deleting Text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @cindex deletion vs killing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 Deletion means removing part of the text in a buffer, without saving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 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
478 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
479 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
480 cases.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 All of the deletion functions operate on the current buffer, and all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 return a value of @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
485 @deffn Command erase-buffer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 This function deletes the entire text of the current buffer, leaving it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
488 error; if some of the text in it is read-only, it signals a
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
489 @code{text-read-only} error. Otherwise, it deletes the text without
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
490 asking for any confirmation. It returns @code{nil}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
491
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 Normally, deleting a large amount of text from a buffer inhibits further
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 auto-saving of that buffer ``because it has shrunk''. However,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @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
495 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
496 be compared with that of the former text.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
497 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @deffn Command delete-region start end
27654
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
500 This command deletes the text between positions @var{start} and
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
501 @var{end} in the current buffer, and returns @code{nil}. If point was
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
502 inside the deleted region, its value afterward is @var{start}.
12775
a8cd9be43025 Explain how delete-region alters point.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
503 Otherwise, point relocates with the surrounding text, as markers do.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
27654
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
506 @defun delete-and-extract-region start end
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
507 @tindex delete-and-extract-region
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
508 This function deletes the text between positions @var{start} and
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
509 @var{end} in the current buffer, and returns a string containing the
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
510 text just deleted.
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
511
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
512 If point was inside the deleted region, its value afterward is
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
513 @var{start}. Otherwise, point relocates with the surrounding text, as
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
514 markers do.
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
515 @end defun
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
516
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @deffn Command delete-char count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 This command deletes @var{count} characters directly after point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 before point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 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
521
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 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
525 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 @deffn Command delete-backward-char count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @cindex delete previous char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 This command deletes @var{count} characters directly before point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 after point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 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
536
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 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
540 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @deffn Command backward-delete-char-untabify count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @cindex tab deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 This command deletes @var{count} characters backward, changing tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 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
550 first replaced with the proper number of spaces to preserve alignment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 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
552 @var{killp} is non-@code{nil}, then the command saves the deleted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 characters in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 Conversion of tabs to spaces happens only if @var{count} is positive.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 If it is negative, exactly @minus{}@var{count} characters after point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 are deleted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 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
562 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
568 @defopt backward-delete-char-untabify-method
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
569 This option specifies how @code{backward-delete-char-untabify} should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
570 deal with whitespace. Possible values include @code{untabify}, the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
571 default, meaning convert a tab to many spaces and delete one;
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
572 @code{hungry}, meaning delete all the whitespace characters before point
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
573 with one command, and @code{nil}, meaning do nothing special for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
574 whitespace characters.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
575 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
576
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @node User-Level Deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @section User-Level Deletion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 This section describes higher-level commands for deleting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 programs.
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 @deffn Command delete-horizontal-space
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @cindex deleting whitespace
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 This function deletes all spaces and tabs around point. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 In the following examples, we call @code{delete-horizontal-space} four
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 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
591 characters on the line each time.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 I @point{}thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 I @point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 We@point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 Yo@point{}u thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602
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 (delete-horizontal-space) ; @r{Four times.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606
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 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 Wethought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 You thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @end deffn
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 @deffn Command delete-indentation &optional join-following-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 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
619 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
620 space. If @var{join-following-p} is non-@code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @code{delete-indentation} joins this line to the following line
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
622 instead. The function returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 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
625 starts with the prefix, then @code{delete-indentation} deletes the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
626 fill prefix before joining the lines. @xref{Margins}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 In the example below, point is located on the line starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @samp{events}, and it makes no difference if there are trailing spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 in the preceding line.
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 @smallexample
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
633 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 When in the course of human
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 @point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
638 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 (delete-indentation)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
643 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 When in the course of human@point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
647 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 After the lines are joined, the function @code{fixup-whitespace} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 responsible for deciding whether to leave a space at the junction.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @defun fixup-whitespace
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
655 This function replaces all the whitespace surrounding point with either
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 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
657
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 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
659 none. Before a character with close parenthesis syntax, or after a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 character with open parenthesis or expression-prefix syntax, no space is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 Class Table}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 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
665 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
666 second invocation, point is directly after the @samp{(}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 This has too many @point{}spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 This has too many spaces at the start of (@point{} this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 This has too many spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 This has too many spaces at the start of (this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 @end defun
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 @deffn Command just-one-space
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 This command replaces any spaces and tabs around point with a single
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 space. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @deffn Command delete-blank-lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 This function deletes blank lines surrounding point. If point is on a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 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
701 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
702 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
703 blank lines following it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 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
706
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @code{delete-blank-lines} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @node The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @section The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @cindex kill ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
714 @dfn{Kill functions} delete text like the deletion functions, but save
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 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
716 functions have @samp{kill-} in their name. By contrast, the functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 whose names start with @samp{delete-} normally do not save text for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 yanking (though they can still be undone); these are ``deletion''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 Most of the kill commands are primarily for interactive use, and are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 not described here. What we do describe are the functions provided for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 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
724 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
725 purposes within a Lisp function, you should normally use deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 functions, so as not to disturb the kill ring contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @xref{Deletion}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 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
730 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
731 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
732 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
733 @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
734 lists; there are also specialized functions, described in this section,
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
735 that treat it as a ring.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 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
738 it refers to operations that specifically @emph{do not} destroy the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 entities ``killed''. This is in sharp contrast to ordinary life, in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 which death is permanent and ``killed'' entities do not come back to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 life. Therefore, other metaphors have been proposed. For example, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 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
743 scissors and paste to cut up and rearrange manuscripts. However, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 would be difficult to change the terminology now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 * Kill Ring Concepts:: What text looks like in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 * Kill Functions:: Functions that kill text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 * Yank Commands:: Commands that access the kill ring.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
750 * Low-Level Kill Ring:: Functions and variables for kill ring access.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 * Internals of Kill Ring:: Variables that hold kill-ring data.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @node Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @subsection Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 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
759 first. A short kill ring, for example, might look like this:
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 ("some text" "a different piece of text" "even older text")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 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
767 new entry automatically deletes the last entry.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 When kill commands are interwoven with other commands, each kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 command makes a new entry in the kill ring. Multiple kill commands in
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
771 succession build up a single kill-ring entry, which would be yanked as a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
772 unit; the second and subsequent consecutive kill commands add text to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
773 the entry made by the first one.
6558
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 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
776 the ring. Some yank commands ``rotate'' the ring by designating a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 different element as the ``front.'' But this virtual rotation doesn't
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 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
779 list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @node Kill Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 @subsection Functions for Killing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @code{kill-region} is the usual subroutine for killing text. Any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 command that calls this function is a ``kill command'' (and should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 probably have @samp{kill} in its name). @code{kill-region} puts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 newly killed text in a new element at the beginning of the kill ring or
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
789 adds it to the most recent element. It determines automatically (using
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
790 @code{last-command}) whether the previous command was a kill command,
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
791 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
792
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @deffn Command kill-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 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
795 @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
796 its text properties. The value is always @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 In an interactive call, @var{start} and @var{end} are point and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 the mark.
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 @c Emacs 19 feature
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
802 If the buffer or text is read-only, @code{kill-region} modifies the kill
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
803 ring just the same, then signals an error without modifying the buffer.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
804 This is convenient because it lets the user use a series of kill
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
805 commands to copy text from a read-only buffer into the kill ring.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
808 @defopt kill-read-only-ok
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
809 If this option is non-@code{nil}, @code{kill-region} does not signal an
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
810 error if the buffer or text is read-only. Instead, it simply returns,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
811 updating the kill ring but not changing the buffer.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
812 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
813
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @deffn Command copy-region-as-kill start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 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
816 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
817 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
818 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
819 message in the echo area.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
821 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
822 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
823
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
825 support Emacs 18. For newer Emacs versions, it is better to use
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
826 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
827 Ring}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @node Yank Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 @subsection Functions for Yanking
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 @dfn{Yanking} means reinserting an entry of previously killed text
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
835 from the kill ring. The text properties are copied too.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @deffn Command yank &optional arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @cindex inserting killed text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 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
840 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
841 point at the end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 If @var{arg} is a list (which occurs interactively when the user
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 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
845 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
846 after it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 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
849 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
850
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @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
852 It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @deffn Command yank-pop arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 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
857 different entry from the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 This is allowed only immediately after a @code{yank} or another
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @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
861 inserted by yanking. @code{yank-pop} deletes that text and inserts in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 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
863 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
864
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 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
866 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
867 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
868 kill is the replacement.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 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
871 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
872 oldest.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
874 The return value is always @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
877 @node Low-Level Kill Ring
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
878 @subsection Low-Level Kill Ring
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
880 These functions and variables provide access to the kill ring at a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
881 lower level, but still convenient for use in Lisp programs, because they
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
882 take care of interaction with window system selections
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
883 (@pxref{Window System Selections}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @defun current-kill n &optional do-not-move
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
886 The function @code{current-kill} rotates the yanking pointer, which
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
887 designates the ``front'' of the kill ring, by @var{n} places (from newer
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
888 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
889
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 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
891 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
892 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
893
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 If @var{n} is zero, indicating a request for the latest kill,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @code{current-kill} calls the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 @code{interprogram-paste-function} (documented below) before consulting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 @defun kill-new string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 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
902 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
903 appropriate. It also invokes the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 @code{interprogram-cut-function} (see below).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @end defun
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 @defun kill-append string before-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 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
909 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
910 @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
911 function also invokes the value of @code{interprogram-cut-function} (see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 below).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @defvar interprogram-paste-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 This variable provides a way of transferring killed text from other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 programs, when you are using a window system. Its value should be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 @code{nil} or a function of no arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 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
921 ``most recent kill''. If the function returns a non-@code{nil} value,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 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
923 @code{nil}, then the first element of @code{kill-ring} is used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
925 The normal use of this hook is to get the window system's primary
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
926 selection as the most recent kill, even if the selection belongs to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
927 another application. @xref{Window System Selections}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 @defvar interprogram-cut-function
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
931 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
932 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
933 @code{nil} or a function of one argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 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
936 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
937
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
938 The normal use of this hook is to set the window system's primary
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
939 selection from the newly killed text. @xref{Window System Selections}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 @node Internals of Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @subsection Internals of the Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 The variable @code{kill-ring} holds the kill ring contents, in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 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
948 of the list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 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
951 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
952 identifies the ``front'' of the ring. Moving
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 @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
954 @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
955 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
956 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
957 virtual; it does not change the value of @code{kill-ring}.
6558
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 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 variables whose values are normally lists. The word ``pointer'' in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 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
962 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
963 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 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
966 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
967 @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
968 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
969 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
970
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 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
972 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
973 different piece of text" "yet older text")}.
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
977 kill-ring ---- kill-ring-yank-pointer
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
978 | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
979 | v
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
980 | --- --- --- --- --- ---
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
981 --> | | |------> | | |--> | | |--> nil
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
982 --- --- --- --- --- ---
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 | | -->"yet older text"
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 | --> "a different piece of text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 --> "some text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 This state of affairs might occur after @kbd{C-y} (@code{yank})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 immediately followed by @kbd{M-y} (@code{yank-pop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @defvar kill-ring
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
998 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
999 killed first.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @defvar kill-ring-yank-pointer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 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
1004 ``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
1005 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
1006 that @kbd{C-y} should yank.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 @end defvar
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 @defopt kill-ring-max
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 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
1011 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
1012 value for @code{kill-ring-max} is 30.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @node Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @section Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 @cindex redo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1020 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
1021 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
1022 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
1023 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
1024 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
1025 list, which is in the variable @code{buffer-undo-list}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 @defvar buffer-undo-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 This variable's value is the undo list of the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 A value of @code{t} disables the recording of undo information.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @end defvar
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 Here are the kinds of elements an undo list can have:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 @table @code
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1035 @item @var{position}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1036 This kind of element records a previous value of point; undoing this
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1037 element moves point to @var{position}. Ordinary cursor motion does not
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1038 make any sort of undo record, but deletion operations use these entries
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1039 to record where point was before the command.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 @item (@var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 This kind of element indicates how to delete text that was inserted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 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
1044 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
1046 @item (@var{text} . @var{position})
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 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
1048 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
1049 reinsert it is @code{(abs @var{position})}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 @item (t @var{high} . @var{low})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 This kind of element indicates that an unmodified buffer became
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 modified. The elements @var{high} and @var{low} are two integers, each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 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
1055 was previously visited or saved. @code{primitive-undo} uses those
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 values to determine whether to mark the buffer as unmodified once again;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 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
1058
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @item (nil @var{property} @var{value} @var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 This kind of element records a change in a text property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 Here's how you might undo the change:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 (put-text-property @var{beg} @var{end} @var{property} @var{value})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1067 @item (@var{marker} . @var{adjustment})
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1068 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
1069 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
1070 @var{adjustment} character positions. Undoing this element moves
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1071 @var{marker} @minus{} @var{adjustment} characters.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1072
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 This element is a boundary. The elements between two boundaries are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 called a @dfn{change group}; normally, each change group corresponds to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 one keyboard command, and undo commands normally undo an entire group as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 a unit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 @defun undo-boundary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 This function places a boundary element in the undo list. The undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 command stops at such a boundary, and successive undo commands undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 to earlier and earlier boundaries. This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084
11555
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1085 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
1086 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
1087 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
1088 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
1089 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
1090 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
1091 self-inserting characters continue.
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1092
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1093 All buffer modifications add a boundary whenever the previous undoable
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1094 change was made in some other buffer. This is to ensure that
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1095 each command makes a boundary in each buffer where it makes changes.
11555
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1096
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1097 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
1098 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
1099 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
1100 undo individual replacements one by one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @defun primitive-undo count list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 This is the basic function for undoing elements of an undo list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 It undoes the first @var{count} elements of @var{list}, returning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 the rest of @var{list}. You could write this function in Lisp,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 but it is convenient to have it in C.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @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
1110 changes the buffer. Undo commands avoid confusion by saving the undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 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
1112 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
1113 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
1114 continuing to undo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 @end defun
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 @node Maintaining Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 @section Maintaining Undo Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 This section describes how to enable and disable undo information for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121 a given buffer. It also explains how the undo list is truncated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 automatically so it doesn't get too big.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 Recording of undo information in a newly created buffer is normally
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 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
1126 undo recording is initially disabled. You can explicitly enable or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 disable undo recording with the following two functions, or by setting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @code{buffer-undo-list} yourself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @deffn Command buffer-enable-undo &optional buffer-or-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 This command enables recording undo information for buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @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
1133 argument is supplied, then the current buffer is used. This function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 does nothing if undo recording is already enabled in the buffer. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 In an interactive call, @var{buffer-or-name} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 You cannot specify any other buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1141 @deffn Command buffer-disable-undo &optional buffer
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1142 @deffnx Command buffer-flush-undo &optional buffer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @cindex disable undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 This function discards the undo list of @var{buffer}, and disables
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 further recording of undo information. As a result, it is no longer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 possible to undo either previous changes or any subsequent changes. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 the undo list of @var{buffer} is already disabled, this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 has no effect.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1150 This function returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 The name @code{buffer-flush-undo} is not considered obsolete, but the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1153 preferred name is @code{buffer-disable-undo}.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1154 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 As editing continues, undo lists get longer and longer. To prevent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 them from using up all available memory space, garbage collection trims
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 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
1159 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
1160 strings of deleted text.) Two variables control the range of acceptable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 sizes: @code{undo-limit} and @code{undo-strong-limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @defvar undo-limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 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
1165 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
1166 @end defvar
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 @defvar undo-strong-limit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1169 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
1170 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
1171 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
1172 change group is never discarded no matter how big it is.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 @end defvar
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 @node Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 @section Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @cindex filling, explicit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 @dfn{Filling} means adjusting the lengths of lines (by moving the line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 breaks) so that they are nearly (but no greater than) a specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 maximum width. Additionally, lines can be @dfn{justified}, which means
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1183 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
1184 precisely. The width is controlled by the variable @code{fill-column}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1185 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
1186
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 automatically as you insert it, but changes to existing text may leave
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 it improperly filled. Then you must fill the text explicitly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1191 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
1192 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
1193 left margin, current right margin, and current justification style
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1194 (@pxref{Margins}). If the current justification style is
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1195 @code{none}, the filling functions don't actually do anything.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1196
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1197 Several of the filling functions have an argument @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1198 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
1199 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
1200 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
1201 means to use the current justification style for this part of the text
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1202 (see @code{current-justification}, below). Any other value is treated
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1203 as @code{full}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1204
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1205 When you call the filling functions interactively, using a prefix
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1206 argument implies the value @code{full} for @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1207
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1208 @deffn Command fill-paragraph justify
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @cindex filling a paragraph
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 This command fills the paragraph at or after point. If
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1211 @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
1212 It uses the ordinary paragraph motion commands to find paragraph
38581
9f3e1a8c8870 Fixing some typos.
Werner LEMBERG <wl@gnu.org>
parents: 34000
diff changeset
1213 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215
25454
80ac191b6d2b *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
1216 @deffn Command fill-region start end &optional justify nosqueeze to-eop
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 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
1218 to @var{end}. It justifies as well if @var{justify} is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 non-@code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1221 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1222 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1223 that means to keep filling to the end of the paragraph---or the next hard
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1224 newline, if @code{use-hard-newlines} is enabled (see below).
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1225
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 The variable @code{paragraph-separate} controls how to distinguish
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 paragraphs. @xref{Standard Regexps}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1230 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 This command fills each paragraph in the region according to its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 individual fill prefix. Thus, if the lines of a paragraph were indented
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 with spaces, the filled paragraph will remain indented in the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 The first two arguments, @var{start} and @var{end}, are the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 and end of the region to be filled. The third and fourth arguments,
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1238 @var{justify} and @var{citation-regexp}, are optional. If
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1239 @var{justify} is non-@code{nil}, the paragraphs are justified as
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1240 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 function is operating on a mail message and therefore should not fill
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1242 the header lines. If @var{citation-regexp} is a string, it is used as
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1243 a regular expression; if it matches the beginning of a line, that line
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1244 is treated as a citation marker.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 Ordinarily, @code{fill-individual-paragraphs} regards each change in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 indentation as starting a new paragraph. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 @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
1249 separator lines separate paragraphs. That mode can handle indented
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1250 paragraphs with additional indentation on the first line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @defopt fill-individual-varying-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 This variable alters the action of @code{fill-individual-paragraphs} as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 described above.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1258 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1259 This command considers a region of text as a single paragraph and fills
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1260 it. If the region was made up of many paragraphs, the blank lines
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1261 between paragraphs are removed. This function justifies as well as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1262 filling when @var{justify} is non-@code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1263
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1264 In an interactive call, any prefix argument requests justification.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1266 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1267 other than line breaks untouched. If @var{squeeze-after} is
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1268 non-@code{nil}, it specifies a position in the region, and means don't
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1269 canonicalize spaces before that position.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1270
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1271 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1272 choose a fill prefix by default. @xref{Adaptive Fill}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1275 @deffn Command justify-current-line &optional how eop nosqueeze
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 This command inserts spaces between the words of the current line so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 that the line ends exactly at @code{fill-column}. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 @code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1279
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1280 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
1281 of justification. It can be @code{left}, @code{right}, @code{full},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1282 @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
1283 follow specified justification style (see @code{current-justification},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1284 below). @code{nil} means to do full justification.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1285
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16702
diff changeset
1286 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
1287 @code{current-justification} specifies full justification. This is used
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1288 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
1289 fully justified, the last line should not be.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1290
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1291 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
1292 whitespace.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1295 @defopt default-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1296 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
1297 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
1298 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
1299 @code{none}. The default value is @code{left}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1300 @end defopt
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1301
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1302 @defun current-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1303 This function returns the proper justification style to use for filling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1304 the text around point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1305 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1306
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1307 @defopt sentence-end-double-space
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1308 If this variable is non-@code{nil}, a period followed by just one space
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1309 does not count as the end of a sentence, and the filling functions
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1310 avoid breaking the line at such a place.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1311 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1312
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1313 @defvar fill-paragraph-function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1314 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
1315 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
1316 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
1317 value, @code{fill-paragraph} assumes the job is done, and immediately
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1318 returns that value.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1319
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1320 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
1321 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
1322 way, it can do so as follows:
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1323
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1324 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1325 (let ((fill-paragraph-function nil))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1326 (fill-paragraph arg))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1327 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1328 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1329
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1330 @defvar use-hard-newlines
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1331 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
1332 newlines that have the @code{hard} text property. These ``hard
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1333 newlines'' act as paragraph separators.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1334 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1335
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1336 @node Margins
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1337 @section Margins for Filling
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1338
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1339 @defopt fill-prefix
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1340 This buffer-local variable specifies a string of text that appears at
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1341 the beginning
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1342 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
1343 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
1344 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
1345 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
1346 additional whitespace are ordinary text lines that can be filled
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1347 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
1348
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1349 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
1350 @end defopt
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1351
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1352 @defopt fill-column
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1353 This buffer-local variable specifies the maximum width of filled lines.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1354 Its value should be an integer, which is a number of columns. All the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1355 filling, justification, and centering commands are affected by this
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1356 variable, including Auto Fill mode (@pxref{Auto Filling}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 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
1359 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
1360 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
1361 make the text seem clumsy.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1362 @end defopt
6558
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 @defvar default-fill-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 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
1366 buffers that do not override it. This is the same as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @code{(default-value 'fill-column)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 The default value for @code{default-fill-column} is 70.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1372 @deffn Command set-left-margin from to margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1373 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
1374 @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
1375 command also refills the region to fit the new margin.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1376 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1377
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1378 @deffn Command set-right-margin from to margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1379 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
1380 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
1381 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
1382 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1383
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1384 @defun current-left-margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1385 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
1386 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
1387 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
1388 none), and the value of the variable @code{left-margin}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1389 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1390
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1391 @defun current-fill-column
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1392 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
1393 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
1394 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
1395 character after point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1396 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1397
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1398 @deffn Command move-to-left-margin &optional n force
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1399 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
1400 column moved to is determined by calling the function
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1401 @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
1402 @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
1403
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1404 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
1405 indentation if that doesn't match the left margin value.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1406 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1407
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1408 @defun delete-to-left-margin &optional from to
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1409 This function removes left margin indentation from the text between
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1410 @var{from} and @var{to}. The amount of indentation to delete is
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1411 determined by calling @code{current-left-margin}. In no case does this
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1412 function delete non-whitespace. If @var{from} and @var{to} are omitted,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1413 they default to the whole buffer.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1414 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1415
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1416 @defun indent-to-left-margin
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1417 This is the default @code{indent-line-function}, used in Fundamental
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1418 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
1419 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
1420 @code{left-margin}. This may involve either inserting or deleting
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1421 whitespace.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1422 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1423
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1424 @defvar left-margin
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1425 This variable specifies the base left margin column. In Fundamental
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1426 mode, @kbd{C-j} indents to this column. This variable automatically
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1427 becomes buffer-local when set in any fashion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1428 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1429
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1430 @defvar fill-nobreak-predicate
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1431 This variable gives major modes a way to specify not to break a line at
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1432 certain places. Its value should be a function. This function is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1433 called during filling, with no arguments and with point located at the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1434 place where a break is being considered. If the function returns
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1435 non-@code{nil}, then the line won't be broken there.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1436 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1437
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1438 @node Adaptive Fill
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1439 @section Adaptive Fill Mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1440 @cindex Adaptive Fill mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1441
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1442 Adaptive Fill mode chooses a fill prefix automatically from the text
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1443 in each paragraph being filled.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1444
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1445 @defopt adaptive-fill-mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1446 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1447 It is @code{t} by default.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1448 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1449
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1450 @defun fill-context-prefix from to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1451 This function implements the heart of Adaptive Fill mode; it chooses a
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1452 fill prefix based on the text between @var{from} and @var{to}. It does
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1453 this by looking at the first two lines of the paragraph, based on the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1454 variables described below.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1455 @c The optional argument first-line-regexp is not documented
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1456 @c because it exists for internal purposes and might be eliminated
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1457 @c in the future.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1458 @end defun
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1459
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1460 @defopt adaptive-fill-regexp
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1461 This variable holds a regular expression to control Adaptive Fill mode.
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1462 Adaptive Fill mode matches this regular expression against the text
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1463 starting after the left margin whitespace (if any) on a line; the
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1464 characters it matches are that line's candidate for the fill prefix.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1465 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1466
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1467 @defopt adaptive-fill-first-line-regexp
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1468 In a one-line paragraph, if the candidate fill prefix matches this
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1469 regular expression, or if it matches @code{comment-start-skip}, then it
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1470 is used---otherwise, spaces amounting to the same width are used
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1471 instead.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1472
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1473 However, the fill prefix is never taken from a one-line paragraph
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1474 if it would act as a paragraph starter on subsequent lines.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1475 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1476
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1477 @defopt adaptive-fill-function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1478 You can specify more complex ways of choosing a fill prefix
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1479 automatically by setting this variable to a function. The function is
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1480 called when @code{adaptive-fill-regexp} does not match, with point after
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1481 the left margin of a line, and it should return the appropriate fill
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1482 prefix based on that line. If it returns @code{nil}, that means it sees
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1483 no fill prefix in that line.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1484 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1485
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 @node Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 @section Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 @cindex filling, automatic
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 @cindex Auto Fill mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1492 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
1493 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
1494 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
1495 justify existing text, see @ref{Filling}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1497 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
1498 justification style to refill portions of the text. @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1499
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 @defvar auto-fill-function
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1501 The value of this variable should be a function (of no arguments) to be
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1502 called after self-inserting a character from the table
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1503 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1504 special is done in that case.
6558
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 @code{auto-fill-function} is @code{do-auto-fill} when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 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
1508 implement the usual strategy for breaking a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 In older Emacs versions, this variable was named @code{auto-fill-hook},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 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
1513 was renamed to @code{auto-fill-function} in version 19.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516
16702
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1517 @defvar normal-auto-fill-function
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1518 This variable specifies the function to use for
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1519 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1520 modes can set buffer-local values for this variable to alter how Auto
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1521 Fill works.
16702
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1522 @end defvar
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1523
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1524 @defvar auto-fill-chars
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1525 A char table of characters which invoke @code{auto-fill-function} when
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1526 self-inserted---space and newline in most language environments. They
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1527 have an entry @code{t} in the table.
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1528 @end defvar
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1529
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @node Sorting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 @section Sorting Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 @cindex sorting text
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 The sorting functions described in this section all rearrange text in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 a buffer. This is in contrast to the function @code{sort}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 rearranges the order of the elements of a list (@pxref{Rearrangement}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 The values returned by these functions are not meaningful.
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 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1540 This function is the general text-sorting routine that subdivides a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1541 buffer into records and then sorts them. Most of the commands in this
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1542 section use this function.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 To understand how @code{sort-subr} works, consider the whole accessible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 portion of the buffer as being divided into disjoint pieces called
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1546 @dfn{sort records}. The records may or may not be contiguous, but they
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1547 must not overlap. A portion of each sort record (perhaps all of it) is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 designated as the sort key. Sorting rearranges the records in order by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 their sort keys.
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 Usually, the records are rearranged in order of ascending sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 If the first argument to the @code{sort-subr} function, @var{reverse},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 is non-@code{nil}, the sort records are rearranged in order of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 descending sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 The next four arguments to @code{sort-subr} are functions that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 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
1558 from within @code{sort-subr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 @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
1563 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
1564 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
1565 called. Therefore, you should usually move point to the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566 the buffer before calling @code{sort-subr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 This function can indicate there are no more sort records by leaving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 point at the end of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 @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
1573 the end of the record.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576 @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
1577 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
1578 the whole record is the sort key. If supplied, the function should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 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
1580 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
1581 starting at point. In the latter case, @var{endkeyfun} is called to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582 find the end of the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 @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
1586 to the end of the sort key. This argument is optional. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588 @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
1589 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 non-@code{nil} value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 @end enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593 As an example of @code{sort-subr}, here is the complete function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594 definition for @code{sort-lines}:
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1597 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1598 ;; @r{Note that the first two lines of doc string}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599 ;; @r{are effectively one line when viewed by a user.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1600 (defun sort-lines (reverse beg end)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1601 "Sort lines in region alphabetically;\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1602 argument means descending order.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 Called from a program, there are three arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1606 REVERSE (non-nil means reverse order),\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1607 BEG and END (region to sort).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1608 The variable `sort-fold-case' determines\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1609 whether alphabetic case affects
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1610 the sort order.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1611 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1612 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613 (interactive "P\nr")
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1614 (save-excursion
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1615 (save-restriction
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1616 (narrow-to-region beg end)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1617 (goto-char (point-min))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1618 (sort-subr reverse 'forward-line 'end-of-line))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 @end example
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 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
1623 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
1624 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 record is used as the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 The @code{sort-paragraphs} function is very much the same, except that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 its @code{sort-subr} call looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 (sort-subr reverse
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1633 (function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1634 (lambda ()
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1635 (while (and (not (eobp))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1636 (looking-at paragraph-separate))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1637 (forward-line 1))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 'forward-paragraph)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1641
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1642 Markers pointing into any sort records are left with no useful
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1643 position after @code{sort-subr} returns.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1646 @defopt sort-fold-case
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1647 If this variable is non-@code{nil}, @code{sort-subr} and the other
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1648 buffer sorting functions ignore case when comparing strings.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1649 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1650
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1652 This command sorts the region between @var{start} and @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1654 If @var{reverse} is a negative integer, then sorting is in reverse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655 order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657 Alphabetical sorting means that two sort keys are compared by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 comparing the first characters of each, the second characters of each,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659 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
1660 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
1661 mismatch is the lesser sort key. The individual characters are compared
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1662 according to their numerical character codes in the Emacs character set.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1663
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1664 The value of the @var{record-regexp} argument specifies how to divide
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1665 the buffer into sort records. At the end of each record, a search is
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1666 done for this regular expression, and the text that matches it is taken
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1667 as the next record. For example, the regular expression @samp{^.+$},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1668 which matches lines with at least one character besides a newline, would
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1669 make each such line into a sort record. @xref{Regular Expressions}, for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1670 a description of the syntax and meaning of regular expressions.
6558
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 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
1673 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
1674 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
1675 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
1676 the record moves to its new position.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1678 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
1679 subexpression of @var{record-regexp}, or it can be a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680 on its own.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 If @var{key-regexp} is:
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 @table @asis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685 @item @samp{\@var{digit}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687 grouping in @var{record-regexp} is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1688
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1689 @item @samp{\&}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1690 then the whole record is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 @item a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 then @code{sort-regexp-fields} searches for a match for the regular
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694 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
1695 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
1696 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
1697 changed. (The other records may move around it.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1699
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 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
1701 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
1702 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1703 @samp{\<f\w*\>}. The resulting expression looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1708 (region-beginning)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1709 (region-end))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1710 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1711 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1712
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 If you call @code{sort-regexp-fields} interactively, it prompts for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1714 @var{record-regexp} and @var{key-regexp} in the minibuffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1715 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 @deffn Command sort-lines reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 This command alphabetically sorts lines in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719 @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
1720 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723 @deffn Command sort-paragraphs reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 This command alphabetically sorts paragraphs in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 @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
1726 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729 @deffn Command sort-pages reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 This command alphabetically sorts pages in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 @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
1732 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1733 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1734
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1735 @deffn Command sort-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736 This command sorts lines in the region between @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1737 @var{end}, comparing them alphabetically by the @var{field}th field
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1738 of each line. Fields are separated by whitespace and numbered starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1739 from 1. If @var{field} is negative, sorting is by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1740 @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
1741 is useful for sorting tables.
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 sort-numeric-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1745 This command sorts lines in the region between @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1746 @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
1747 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
1748 region. Fields are separated by whitespace and numbered starting from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1749 1. If @var{field} is negative, sorting is by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 @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
1751 is useful for sorting tables.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1752 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 @deffn Command sort-columns reverse &optional beg end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755 This command sorts the lines in the region between @var{beg} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756 @var{end}, comparing them alphabetically by a certain range of columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1757 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
1758 columns to sort on.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760 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
1761
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 One unusual thing about this command is that the entire line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 containing position @var{beg}, and the entire line containing position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 @var{end}, are included in the region sorted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1766 Note that @code{sort-columns} uses the @code{sort} utility program,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 and so cannot work properly on text containing tab characters. Use
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1768 @kbd{M-x untabify} to convert tabs to spaces before sorting.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @node Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 @section Counting Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774 @cindex columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1775 @cindex counting columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1776 @cindex horizontal position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1778 The column functions convert between a character position (counting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 characters from the beginning of the buffer) and a column position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1780 (counting screen characters from the beginning of a line).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1781
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1782 These functions count each character according to the number of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1783 columns it occupies on the screen. This means control characters count
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1784 as occupying 2 or 4 columns, depending upon the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1785 @code{ctl-arrow}, and tabs count as occupying a number of columns that
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1786 depends on the value of @code{tab-width} and on the column where the tab
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1787 begins. @xref{Usual Display}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1788
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 Column number computations ignore the width of the window and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790 amount of horizontal scrolling. Consequently, a column value can be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1791 arbitrarily high. The first (or leftmost) column is numbered 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1792
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1793 @defun current-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 This function returns the horizontal position of point, measured in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1795 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
1796 sum of the widths of all the displayed representations of the characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 between the start of the current line and point.
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 For an example of using @code{current-column}, see the description of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1800 @code{count-lines} in @ref{Text Lines}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1801 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1802
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1803 @defun move-to-column column &optional force
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1804 This function moves point to @var{column} in the current line. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805 calculation of @var{column} takes into account the widths of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1806 displayed representations of the characters between the start of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 line and point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1809 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
1810 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
1811 beginning of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1812
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1813 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
1814 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
1815 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
1816 @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
1817 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
1818 @var{column}. Other multicolumn characters can cause anomalies despite
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819 @var{force}, since there is no way to split them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1820
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1821 The argument @var{force} also has an effect if the line isn't long
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
1822 enough to reach column @var{column}; if it is @code{t}, that means to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
1823 add whitespace at the end of the line to reach that column.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1824
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1825 If @var{column} is not an integer, an error is signaled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827 The return value is the column number actually moved to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 @node Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 @section Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 @cindex indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1834 The indentation functions are used to examine, move to, and change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 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
1836 can also change whitespace elsewhere on a line. Columns and indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 count from zero at the left margin.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 * Primitive Indent:: Functions used to count and insert indentation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841 * Mode-Specific Indent:: Customize indentation for different modes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 * Region Indent:: Indent all the lines in a region.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 * Relative Indent:: Indent the current line based on previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844 * Indent Tabs:: Adjustable, typewriter-like tab stops.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 * Motion by Indent:: Move to first non-blank character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848 @node Primitive Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 @subsection Indentation Primitives
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 This section describes the primitive functions used to count and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 insert indentation. The functions in the following sections use these
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1853 primitives. @xref{Width}, for related functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 @defun current-indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 This function returns the indentation of the current line, which is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1859 the horizontal position of the first nonblank character. If the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1860 contents are entirely blank, then this is the horizontal position of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1861 end of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864 @deffn Command indent-to column &optional minimum
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1866 @comment !!SourceFile indent.c
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1867 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
1868 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
1869 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
1870 @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
1871 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
1872 indentation ends.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1873
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1874 The inserted whitespace characters inherit text properties from the
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1875 surrounding text (usually, from the preceding text only). @xref{Sticky
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1876 Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1877 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1878
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1879 @defopt indent-tabs-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1880 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1881 If this variable is non-@code{nil}, indentation functions can insert
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1882 tabs as well as spaces. Otherwise, they insert only spaces. Setting
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1883 this variable automatically makes it buffer-local in the current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1884 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886 @node Mode-Specific Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 @subsection Indentation Controlled by Major Mode
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 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
1890 key to indent properly for the language being edited. This section
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 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
1892 The functions in this section return unpredictable values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1893
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1894 @defvar indent-line-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1895 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
1896 various commands) to indent the current line. The command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1897 @code{indent-according-to-mode} does no more than call this function.
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 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
1900 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1901 In Fundamental mode, Text mode, and many other modes with no standard
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1902 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
1903 default value).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1904 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1905
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1906 @deffn Command indent-according-to-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1907 This command calls the function in @code{indent-line-function} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908 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
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-for-tab-command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1912 This command calls the function in @code{indent-line-function} to indent
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1913 the current line; however, if that function is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1914 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1915 is a trivial command that inserts a tab character.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1916 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1917
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1918 @deffn Command newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1920 This function inserts a newline, then indents the new line (the one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1921 following the newline just inserted) according to the major mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1922
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1923 It does indentation by calling the current @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1924 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1925 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1926 @code{newline-and-indent} indents to the column specified by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1927 @code{left-margin}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1928 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1929
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1930 @deffn Command reindent-then-newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1931 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1932 This command reindents the current line, inserts a newline at point,
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1933 and then indents the new line (the one following the newline just
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1934 inserted).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1935
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1936 This command does indentation on both lines according to the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1937 major mode, by calling the current value of @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1938 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1939 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940 @code{reindent-then-newline-and-indent} indents to the column specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 by @code{left-margin}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944 @node Region Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 @subsection Indenting an Entire Region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1947 This section describes commands that indent all the lines in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948 region. They return unpredictable values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1950 @deffn Command indent-region start end to-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951 This command indents each nonblank line starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 (inclusive) and @var{end} (exclusive). If @var{to-column} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1953 @code{nil}, @code{indent-region} indents each nonblank line by calling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1954 the current mode's indentation function, the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1955 @code{indent-line-function}.
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 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
1958 specifying the number of columns of indentation; then this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 gives each line exactly that much indentation, by either adding or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 deleting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962 If there is a fill prefix, @code{indent-region} indents each line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 by making it start with the fill prefix.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1965
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1966 @defvar indent-region-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967 The value of this variable is a function that can be used by
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1968 @code{indent-region} as a short cut. It should take two arguments, the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1969 start and end of the region. You should design the function so
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 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
1971 region one by one, but presumably faster.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973 If the value is @code{nil}, there is no short cut, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974 @code{indent-region} actually works line by line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1976 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
1977 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
1978 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
1979 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
1980 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
1981 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
1982
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1983 @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
1984 a different meaning and does not use this variable.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987 @deffn Command indent-rigidly start end count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988 @comment !!SourceFile indent.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1989 This command indents all lines starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1990 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1991 This ``preserves the shape'' of the affected region, moving it as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1992 rigid unit. Consequently, this command is useful not only for indenting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1993 regions of unindented text, but also for indenting regions of formatted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994 code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996 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
1997 indentation to each of the lines beginning in the region specified.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1999 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
2000 @code{indent-rigidly} to indent the text copied from the message being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 replied to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004 @defun indent-code-rigidly start end columns &optional nochange-regexp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 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
2006 that start within strings or comments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2008 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
2009 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
2010 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2011
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2012 @node Relative Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2013 @subsection Indentation Relative to Previous Lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2014
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2015 This section describes two commands that indent the current line
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016 based on the contents of previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018 @deffn Command indent-relative &optional unindented-ok
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 This command inserts whitespace at point, extending to the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2020 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
2021 indent point is a non-whitespace character following whitespace. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022 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
2023 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
2024 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
2025 by inserting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027 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
2028 great enough column position), @code{indent-relative} either does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2029 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 @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
2031 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
2032 moves point to the next tab stop by inserting whitespace.
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 The return value of @code{indent-relative} is unpredictable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2035
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2036 In the following example, point is at the beginning of the second
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2037 line:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2040 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2041 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2045
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2047 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2048 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2049
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2050 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2051 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2052 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2053 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2054 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2055 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2056
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2057 In this next example, point is between the @samp{m} and @samp{p} of
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2058 @samp{jumped}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2059
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2061 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2062 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2063 The quick brown fox jum@point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2064 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2065 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2066
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2067 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2072 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 The quick brown fox jum @point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 @deffn Command indent-relative-maybe
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080 @comment !!SourceFile indent.el
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2081 This command indents the current line like the previous nonblank line,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2082 by calling @code{indent-relative} with @code{t} as the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2083 @var{unindented-ok} argument. The return value is unpredictable.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2084
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2085 If the previous nonblank line has no indent points beyond the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2086 column, this command does nothing.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2087 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2088
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2089 @node Indent Tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2090 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2091 @subsection Adjustable ``Tab Stops''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092 @cindex tabs stops for indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2093
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 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
2095 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
2096 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
2097 typewriter. The feature works by inserting an appropriate number of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2098 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
2099 affect the display of tab characters in the buffer (@pxref{Usual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 Display}). Note that the @key{TAB} character as input uses this tab
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 stop feature only in a few major modes, such as Text mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2103 @deffn Command tab-to-tab-stop
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2104 This command inserts spaces or tabs before point, up to the next tab
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2105 stop column defined by @code{tab-stop-list}. It searches the list for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2106 an element greater than the current column number, and uses that element
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2107 as the column to indent to. It does nothing if no such element is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2108 found.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2109 @end deffn
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 @defopt tab-stop-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2112 This variable is the list of tab stop columns used by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2113 @code{tab-to-tab-stops}. The elements should be integers in increasing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2114 order. The tab stop columns need not be evenly spaced.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2115
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2116 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
2117 interactively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2118 @end defopt
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 @node Motion by Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2121 @subsection Indentation-Based Motion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2122
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2123 These commands, primarily for interactive use, act based on the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2124 indentation in the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2125
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2126 @deffn Command back-to-indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2127 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2128 This command moves point to the first non-whitespace character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2129 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
2130 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2131 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2133 @deffn Command backward-to-indentation arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2134 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2135 This command moves point backward @var{arg} lines and then to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2136 first nonblank character on that line. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2137 @end deffn
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 @deffn Command forward-to-indentation arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2140 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2141 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
2142 nonblank character on that line. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2143 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2144
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2145 @node Case Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2146 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2147 @section Case Changes
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2148 @cindex case conversion in buffers
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2149
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2150 The case change commands described here work on text in the current
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2151 buffer. @xref{Case Conversion}, for case conversion functions that work
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2152 on strings and characters. @xref{Case Tables}, for how to customize
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2153 which characters are upper or lower case and how to convert them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2154
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2155 @deffn Command capitalize-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2156 This function capitalizes all words in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2157 @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
2158 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
2159 case. The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2160
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2161 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
2162 word within the region is treated as an entire word.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2163
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2164 When @code{capitalize-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2165 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2166
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2167 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2168 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2169 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2170 This is the contents of the 5th foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2171 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2172 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2173
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2174 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2175 (capitalize-region 1 44)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2176 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2177
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2178 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2179 This Is The Contents Of The 5th Foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2180 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2181 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2182 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2183 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2184
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2185 @deffn Command downcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2186 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2187 @var{start} and @var{end} to lower case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2188 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2189
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2190 When @code{downcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2191 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2192 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2193
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2194 @deffn Command upcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2195 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2196 @var{start} and @var{end} to upper case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2197 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2198
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2199 When @code{upcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2200 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2201 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2202
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2203 @deffn Command capitalize-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2204 This function capitalizes @var{count} words after point, moving point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2205 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
2206 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
2207 If @var{count} is negative, the function capitalizes the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2208 @minus{}@var{count} previous words but does not move point. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2209 is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2210
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2211 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
2212 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
2213
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2214 When @code{capitalize-word} is called interactively, @var{count} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2215 set to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2216 @end deffn
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 @deffn Command downcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2219 This function converts the @var{count} words after point to all lower
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2220 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
2221 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2222 The value is @code{nil}.
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 When @code{downcase-word} is called interactively, @var{count} is set
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2225 to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2226 @end deffn
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 @deffn Command upcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2229 This function converts the @var{count} words after point to all upper
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2230 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
2231 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2232 The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2233
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2234 When @code{upcase-word} is called interactively, @var{count} is set to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2235 the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2236 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2237
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238 @node Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 @section Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 @cindex text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241 @cindex attributes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242 @cindex properties of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2244 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
2245 property list}, much like the property list of a symbol (@pxref{Property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 Lists}). The properties belong to a particular character at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2247 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
2248 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
2249 occurs in two different places, the two occurrences generally have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2250 different properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2251
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2252 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
2253 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
2254 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
2255
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2256 If a character has a @code{category} property, we call it the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2257 @dfn{category} of the character. It should be a symbol. The properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2258 of the symbol serve as defaults for the properties of the character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2259
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2260 Copying text between strings and buffers preserves the properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2261 along with the characters; this includes such diverse functions as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262 @code{substring}, @code{insert}, and @code{buffer-substring}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2263
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2264 @menu
40588
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2265 * Examining Properties:: Looking at the properties of one character.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2266 * Changing Properties:: Setting the properties of a range of text.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2267 * Property Search:: Searching for where a property changes value.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2268 * Special Properties:: Particular properties with special meanings.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2269 * Format Properties:: Properties for representing formatting of text.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2270 * Sticky Properties:: How inserted text gets properties from
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2271 neighboring text.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2272 * Saving Properties:: Saving text properties in files, and reading
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2273 them back.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2274 * Lazy Properties:: Computing text properties in a lazy fashion
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2275 only when text is examined.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2276 * Clickable Text:: Using text properties to make regions of text
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2277 do something when you click on them.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2278 * Fields:: The @code{field} property defines
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2279 fields within the buffer.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2280 * Not Intervals:: Why text properties do not use
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2281 Lisp-visible text intervals.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2282 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2283
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2284 @node Examining Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285 @subsection Examining Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2286
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2287 The 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
2288 a particular property of a particular character. For that, use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2289 @code{get-text-property}. Use @code{text-properties-at} to get the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2290 entire property list of a character. @xref{Property Search}, for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2291 functions to examine the properties of a number of characters at once.
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 These functions handle both strings and buffers. Keep in mind that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2294 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
2295 from 1.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2296
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2297 @defun get-text-property pos prop &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2298 This function returns the value of the @var{prop} property of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2299 character after position @var{pos} in @var{object} (a buffer or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300 string). The argument @var{object} is optional and defaults to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2301 current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2302
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2303 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
2304 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
2305 the @var{prop} property of that symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2306 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2307
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2308 @defun get-char-property pos prop &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2309 This function is like @code{get-text-property}, except that it checks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2310 overlays first and then text properties. @xref{Overlays}.
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 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
2313 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
2314 properties and overlays, but only the overlays active for that window
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2315 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
2316 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
2317 string, only text properties are considered, since strings never have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2318 overlays.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2319 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2320
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2321 @defvar char-property-alias-alist
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2322 This variable holds an alist which maps property names to a list of
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2323 alternative property names. If a character does not specify a direct
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2324 value for a property, the alternative property names are consulted in
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2325 order; the first non-nil value is used. This variable takes
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2326 precedence over @code{default-text-properties}, and @code{category}
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2327 properties take precedence over this variable.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2328 @end defvar
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2329
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2330 @defun text-properties-at position &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2331 This function returns the entire property list of the character at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2332 @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
2333 @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2334 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2335
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2336 @defvar default-text-properties
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2337 This variable holds a property list giving default values for text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2338 properties. Whenever a character does not specify a value for a
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2339 property, neither directly, through a category symbol, or through
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2340 @code{char-property-alias-alist}, the value stored in this list is
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2341 used instead. Here is an example:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2342
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2343 @example
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2344 (setq default-text-properties '(foo 69)
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2345 char-property-alias-alist nil)
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2346 ;; @r{Make sure character 1 has no properties of its own.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2347 (set-text-properties 1 2 nil)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2348 ;; @r{What we get, when we ask, is the default value.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2349 (get-text-property 1 'foo)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2350 @result{} 69
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2351 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2352 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2353
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2354 @node Changing Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2355 @subsection Changing Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2356
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2357 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
2358 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
2359 (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
2360 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
2361 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
2362
7def48db254a Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents: 16934
diff changeset
2363 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
2364 buffer (or string), and can affect how a buffer looks on the screen, any
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2365 change in buffer text properties marks the buffer as modified. Buffer
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
2366 text property changes are undoable also (@pxref{Undo}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2367
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2368 @defun put-text-property start end prop value &optional object
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2369 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
2370 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
2371 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
2372 @end defun
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 @defun add-text-properties start end props &optional object
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2375 This function adds or overrides text properties for the text between
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2376 @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
2377 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2378
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2379 The argument @var{props} specifies which properties to add. It should
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2380 have the form of a property list (@pxref{Property Lists}): a list whose
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2381 elements include the property names followed alternately by the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2382 corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2384 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2385 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
2386 its values agree with those in the text).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2387
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2388 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
2389 properties of a range of text:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2391 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2392 (add-text-properties @var{start} @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2393 '(comment t face highlight))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2394 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2395 @end defun
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 @defun remove-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2398 This function deletes specified text properties from the text between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2399 @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
2400 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2401
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2402 The argument @var{props} specifies which properties to delete. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2403 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
2404 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2405 But only the names matter---the values that accompany them are ignored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2406 For example, here's how to remove the @code{face} property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2407
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2408 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2409 (remove-text-properties @var{start} @var{end} '(face nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2410 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2411
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2412 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2413 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
2414 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
2415
7def48db254a Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents: 16934
diff changeset
2416 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
2417 @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
2418 list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2419 @end defun
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 @defun set-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2422 This function completely replaces the text property list for the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2423 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
2424 If @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2425
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2426 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
2427 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2428
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2429 After @code{set-text-properties} returns, all the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2430 specified range have identical properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2431
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2432 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
2433 from the specified range of text. Here's an example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2434
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2435 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2436 (set-text-properties @var{start} @var{end} nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2437 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2438 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2439
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2440 The easiest way to make a string with text properties
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2441 is with @code{propertize}:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2442
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2443 @defun propertize string &rest properties
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2444 @tindex propertize
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2445 This function returns a copy of @var{string} which has the text
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2446 properties @var{properties}. These properties apply to all the
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2447 characters in the string that is returned. Here is an example that
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2448 constructs a string with a @code{face} property and a @code{mouse-face}
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2449 property:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2450
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2451 @smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2452 (propertize "foo" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2453 'mouse-face 'bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2454 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2455 @end smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2456
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2457 To put different properties on various parts of a string, you can
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2458 construct each part with @code{propertize} and then combine them with
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2459 @code{concat}:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2460
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2461 @smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2462 (concat
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2463 (propertize "foo" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2464 'mouse-face 'bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2465 " and "
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2466 (propertize "bar" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2467 'mouse-face 'bold-italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2468 @result{} #("foo and bar"
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2469 0 3 (face italic mouse-face bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2470 3 8 nil
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2471 8 11 (face italic mouse-face bold-italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2472 @end smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2473 @end defun
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2474
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2475 See also the function @code{buffer-substring-no-properties}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2476 (@pxref{Buffer Contents}) which copies text from the buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2477 but does not copy its properties.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2478
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2479 @node Property Search
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2480 @subsection Text Property Search Functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2481
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2482 In typical use of text properties, most of the time several or many
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2483 consecutive characters have the same value for a property. Rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2484 writing your programs to examine characters one by one, it is much
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2485 faster to process chunks of text that have the same property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2486
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2487 Here are functions you can use to do this. They use @code{eq} for
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2488 comparing property values. In all cases, @var{object} defaults to the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2489 current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2490
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2491 For high performance, it's very important to use the @var{limit}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2492 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
2493 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
2494 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
2495
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2496 These functions do not move point; instead, they return a position (or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2497 @code{nil}). Remember that a position is always between two characters;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2498 the position returned by these functions is between two characters with
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2499 different properties.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2500
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2501 @defun next-property-change pos &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2502 The function scans the text forward from position @var{pos} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2503 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
2504 property, then returns the position of the change. In other words, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2505 returns the position of the first character beyond @var{pos} whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2506 properties are not identical to those of the character just after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2507 @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2508
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2509 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
2510 @var{limit}. If there is no property change before that point,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2511 @code{next-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2512
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2513 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
2514 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
2515 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
2516 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
2517
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2518 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
2519 which all properties are constant:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2521 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2522 (while (not (eobp))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2523 (let ((plist (text-properties-at (point)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2524 (next-change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2525 (or (next-property-change (point) (current-buffer))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2526 (point-max))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2527 @r{Process text from point to @var{next-change}@dots{}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2528 (goto-char next-change)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2529 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2530 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2532 @defun next-single-property-change pos prop &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2533 The function scans the text forward from position @var{pos} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2534 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
2535 property, then returns the position of the change. In other words, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2536 returns the position of the first character beyond @var{pos} whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2537 @var{prop} property differs from that of the character just after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2538 @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2539
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2540 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
2541 @var{limit}. If there is no property change before that point,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2542 @code{next-single-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2543
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2544 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
2545 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
2546 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
2547 equals @var{pos} only if @var{limit} equals @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2548 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2549
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2550 @defun previous-property-change pos &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2551 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
2552 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
2553 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
2554 equals @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2555 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2556
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2557 @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
2558 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
2559 @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
2560 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
2561 @var{limit} equals @var{pos}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2562 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2563
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2564 @defun next-char-property-change pos &optional limit
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2565 This is like @code{next-property-change} except that it considers
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2566 overlay properties as well as text properties, and if no change is
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2567 found before the end of the buffer, it returns the maximum buffer
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2568 position rather than @code{nil} (in this sense, it resembles the
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2569 corresponding overlay function @code{next-overlay-change}, rather than
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2570 @code{next-property-change}). There is no @var{object} operand
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2571 because this function operates only on the current buffer. It returns
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2572 the next address at which either kind of property changes.
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2573 @end defun
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2574
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2575 @defun previous-char-property-change pos &optional limit
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2576 This is like @code{next-char-property-change}, but scans back from
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2577 @var{pos} instead of forward, and returns the minimum buffer
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2578 position if no change is found.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2579 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2580
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2581 @defun next-single-char-property-change pos prop &optional object limit
39530
6d1ba806f659 Add @tindex lines to new entries.
Miles Bader <miles@gnu.org>
parents: 39528
diff changeset
2582 @tindex next-single-char-property-change
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2583 This is like @code{next-single-property-change} except that it
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2584 considers overlay properties as well as text properties, and if no
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2585 change is found before the end of the @var{object}, it returns the
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2586 maximum valid position in @var{object} rather than @code{nil}. Unlike
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2587 @code{next-char-property-change}, this function @emph{does} have an
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2588 @var{object} operand; if @var{object} is not a buffer, only
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2589 text-properties are considered.
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2590 @end defun
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2591
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2592 @defun previous-single-char-property-change pos prop &optional object limit
39530
6d1ba806f659 Add @tindex lines to new entries.
Miles Bader <miles@gnu.org>
parents: 39528
diff changeset
2593 @tindex previous-single-char-property-change
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2594 This is like @code{next-single-char-property-change}, but scans back
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2595 from @var{pos} instead of forward, and returns the minimum valid
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2596 position in @var{object} if no change is found.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2597 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2598
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2599 @defun text-property-any start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2600 This function returns non-@code{nil} if at least one character between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2601 @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
2602 @var{value}. More precisely, it returns the position of the first such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2603 character. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2604
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2605 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2606 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2607 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2608 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2610 @defun text-property-not-all start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2611 This function returns non-@code{nil} if at least one character between
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2612 @var{start} and @var{end} does not have a property @var{prop} with value
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2613 @var{value}. More precisely, it returns the position of the first such
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2614 character. Otherwise, it returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2615
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2616 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2617 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2618 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2619 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2620
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2621 @node Special Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2622 @subsection Properties with Special Meanings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2623
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2624 Here is a table of text property names that have special built-in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2625 meanings. The following sections list a few additional special property
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2626 names that control filling and property inheritance. All other names
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2627 have no standard meaning, and you can use them as you like.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2628
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2629 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2630 @cindex category of text character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2631 @kindex category @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2632 @item category
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2633 If a character has a @code{category} property, we call it the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2634 @dfn{category} of the character. It should be a symbol. The properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2635 of the symbol serve as defaults for the properties of the character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2636
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2637 @item face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2638 @cindex face codes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2639 @kindex face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2640 You can use the property @code{face} to control the font and color of
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2641 text. @xref{Faces}, for more information.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2642
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2643 In the simplest case, the value is a face name. It can also be a list;
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2644 then each element can be any of these possibilities;
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2645
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2646 @itemize @bullet
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2647 @item
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2648 A face name (a symbol or string).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2649
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2650 @item
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2651 Starting in Emacs 21, a property list of face attributes. This has the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2652 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2653 face attribute name and @var{value} is a meaningful value for that
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2654 attribute. With this feature, you do not need to create a face each
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2655 time you want to specify a particular attribute for certain text.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2656 @xref{Face Attributes}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2657
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2658 @item
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2659 A cons cell of the form @code{(foreground-color . @var{color-name})} or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2660 @code{(background-color . @var{color-name})}. These elements specify
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2661 just the foreground color or just the background color.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2662
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2663 @code{(foreground-color . @var{color-name})} is equivalent to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2664 @code{(:foreground @var{color-name})}, and likewise for the background.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2665 @end itemize
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2666
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2667 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2668 update @code{face} properties based on the contents of the text.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2669
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2670 @item font-lock-face
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2671 @kindex font-lock-face @r{(text property)}
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2672 The @code{font-lock-face} property is the same in all respects as the
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2673 @code{face} property, but its state of activation is controlled by
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2674 @code{font-lock-mode}. This can be advantageous for special buffers
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2675 which are not intended to be user-editable, or for static areas of
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2676 text which are always fontified in the same way.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2677 @xref{Precalculated Fontification}.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2678
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2679 Strictly speaking, @code{font-lock-face} is not a built-in text
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2680 property; rather, it is implemented in Font Lock mode using
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2681 @code{char-property-alias-alist}. @xref{Examining Properties}.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2682
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2683 This property is new in Emacs 21.4.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2684
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2685 @item mouse-face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2686 @kindex mouse-face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2687 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
2688 mouse is on or near the character. For this purpose, ``near'' means
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2689 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
2690 @code{mouse-face} property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2691
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2692 @item fontified
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2693 @kindex fontified @r{(text property)}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2694 This property, if non-@code{nil}, says that text in the buffer has
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2695 had faces assigned automatically by a feature such as Font-Lock mode.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2696 @xref{Auto Faces}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2697
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2698 @item display
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2699 @kindex display @r{(text property)}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2700 This property activates various features that change the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2701 way text is displayed. For example, it can make text appear taller
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2702 or shorter, higher or lower, wider or narrow, or replaced with an image.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2703 @xref{Display Property}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2704
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2705 @item help-echo
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2706 @kindex help-echo @r{(text property)}
45040
07fdd6ac8356 (Special Properties): Add index entry and xref for tooltips.
Richard M. Stallman <rms@gnu.org>
parents: 43907
diff changeset
2707 @cindex tooltip
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2708 @anchor{Text help-echo}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2709 If text has a string as its @code{help-echo} property, then when you
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2710 move the mouse onto that text, Emacs displays that string in the echo
45040
07fdd6ac8356 (Special Properties): Add index entry and xref for tooltips.
Richard M. Stallman <rms@gnu.org>
parents: 43907
diff changeset
2711 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
07fdd6ac8356 (Special Properties): Add index entry and xref for tooltips.
Richard M. Stallman <rms@gnu.org>
parents: 43907
diff changeset
2712 Manual}).
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2713
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2714 If the value of the @code{help-echo} property is a function, that
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2715 function is called with three arguments, @var{window}, @var{object} and
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2716 @var{position} and should return a help string or @var{nil} for
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2717 none. The first argument, @var{window} is the window in which
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2718 the help was found. The second, @var{object}, is the buffer, overlay or
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2719 string which had the @code{help-echo} property. The @var{position}
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2720 argument is as follows:
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2721
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2722 @itemize @bullet{}
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2723 @item
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2724 If @var{object} is a buffer, @var{pos} is the position in the buffer
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2725 where the @code{help-echo} text property was found.
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2726 @item
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2727 If @var{object} is an overlay, that overlay has a @code{help-echo}
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2728 property, and @var{pos} is the position in the overlay's buffer under
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2729 the mouse.
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2730 @item
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2731 If @var{object} is a string (an overlay string or a string displayed
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2732 with the @code{display} property), @var{pos} is the position in that
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2733 string under the mouse.
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2734 @end itemize
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2735
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2736 If the value of the @code{help-echo} property is neither a function nor
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2737 a string, it is evaluated to obtain a help string.
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2738
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2739 You can alter the way help text is displayed by setting the variable
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2740 @code{show-help-function} (@pxref{Help display}).
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2741
45750
73b33fa2ec78 Delete "new in Emacs 21" note.
Richard M. Stallman <rms@gnu.org>
parents: 45685
diff changeset
2742 This feature is used in the mode line and for other active text.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2743
43907
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2744 @item keymap
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2745 @cindex keymap of character
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2746 @kindex keymap @r{(text property)}
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2747 The @code{keymap} property specifies an additional keymap for
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2748 commands. The property's value for the character after point, if
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2749 non-@code{nil}, is used for key lookup before the buffer's local map.
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2750 (For mouse clicks, the @code{keymap} property of the character clicked
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2751 on is the one used.) If the property value is a symbol, the symbol's
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2752 function definition is used as the keymap. @xref{Active Keymaps}.
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2753
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
2754 @item local-map
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
2755 @kindex local-map @r{(text property)}
43907
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2756 This property specifies a keymap to use @emph{instead of} the buffer's
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2757 local map. If the property value is a symbol, the symbol's function
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2758 definition is used as the keymap. For most purposes (perhaps all
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
2759 purposes), the @code{keymap} is superior.
34000
bbedc7c6ec6f keymap property
Dave Love <fx@gnu.org>
parents: 33911
diff changeset
2760
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2761 @item syntax-table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2762 The @code{syntax-table} property overrides what the syntax table says
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2763 about this particular character. @xref{Syntax Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2764
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2765 @item read-only
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2766 @cindex read-only character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2767 @kindex read-only @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2768 If a character has the property @code{read-only}, then modifying that
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2769 character is not allowed. Any command that would do so gets an error,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2770 @code{text-read-only}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2771
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2772 Insertion next to a read-only character is an error if inserting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2773 ordinary text there would inherit the @code{read-only} property due to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2774 stickiness. Thus, you can control permission to insert next to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2775 read-only text by controlling the stickiness. @xref{Sticky Properties}.
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 Since changing properties counts as modifying the buffer, it is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2778 possible to remove a @code{read-only} property unless you know the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2779 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
2780 and then remove the property. @xref{Read Only Buffers}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2781
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2782 @item invisible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2783 @kindex invisible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2784 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
2785 on the screen. @xref{Invisible Text}, for details.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2786
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2787 @item intangible
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2788 @kindex intangible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2789 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
2790 @code{intangible} properties, then you cannot place point between them.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2791 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
2792 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
2793 point actually moves to the start of the group.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2794
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2795 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
2796 the @code{intangible} property is ignored.
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2797
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2798 @item field
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2799 @kindex field @r{(text property)}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2800 Consecutive characters with the same @code{field} property constitute a
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2801 @dfn{field}. Some motion functions including @code{forward-word} and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2802 @code{beginning-of-line} stop moving at a field boundary.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2803 @xref{Fields}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2804
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2805 @item modification-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2806 @cindex change hooks for a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2807 @cindex hooks for changing a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2808 @kindex modification-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2809 If a character has the property @code{modification-hooks}, then its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2810 value should be a list of functions; modifying that character calls all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2811 of those functions. Each function receives two arguments: the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2812 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
2813 particular modification hook function appears on several characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2814 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
2815 the function will be called.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2816
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2817 @item insert-in-front-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2818 @itemx insert-behind-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2819 @kindex insert-in-front-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2820 @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
2821 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
2822 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
2823 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
2824 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
2825 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
2826 @emph{after} the actual insertion takes place.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2827
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2828 See also @ref{Change Hooks}, for other hooks that are called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2829 when you change text in a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2830
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2831 @item point-entered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2832 @itemx point-left
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2833 @cindex hooks for motion of point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2834 @kindex point-entered @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2835 @kindex point-left @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2836 The special properties @code{point-entered} and @code{point-left}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2837 record hook functions that report motion of point. Each time point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2838 moves, Emacs compares these two property values:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2839
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2840 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2841 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2842 the @code{point-left} property of the character after the old location,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2843 and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2844 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2845 the @code{point-entered} property of the character after the new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2846 location.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2847 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2848
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2849 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2850 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
2851 with two arguments: the old value of point, and the new one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2852
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2853 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
2854 locations. The result may be to execute two @code{point-left} functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2855 (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
2856 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
2857 @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
2858 @code{point-entered} functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2859
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2860 It is possible using @code{char-after} to examine characters at various
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2861 positions without moving point to those positions. Only an actual
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2862 change in the value of point runs these hook functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2863 @end table
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 @defvar inhibit-point-motion-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2866 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
2867 @code{point-entered} hooks are not run, and the @code{intangible}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2868 property has no effect. Do not set this variable globally; bind it with
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2869 @code{let}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2870 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2871
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2872 @defvar show-help-function
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2873 @tindex show-help-function
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2874 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2875 function called to display help strings. These may be @code{help-echo}
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2876 properties, menu help strings (@pxref{Simple Menu Items},
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2877 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
2878 Bar}). The specified function is called with one argument, the help
38581
9f3e1a8c8870 Fixing some typos.
Werner LEMBERG <wl@gnu.org>
parents: 34000
diff changeset
2879 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
9f3e1a8c8870 Fixing some typos.
Werner LEMBERG <wl@gnu.org>
parents: 34000
diff changeset
2880 Manual}) provides an example.
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2881 @end defvar
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
2882
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2883 @node Format Properties
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2884 @subsection Formatted Text Properties
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2885
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2886 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
2887 are used for representing formatted text. @xref{Filling}, and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2888 @ref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2889
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2890 @table @code
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2891 @item hard
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2892 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
2893 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
2894 across them. However, this property takes effect only if the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2895 @code{use-hard-newlines} is non-@code{nil}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2896
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2897 @item right-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2898 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
2899 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2900
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2901 @item left-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2902 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
2903 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2904
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2905 @item justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2906 This property specifies the style of justification for filling this part
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2907 of the text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2908 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2909
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2910 @node Sticky Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2911 @subsection Stickiness of Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2912 @cindex sticky text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2913 @cindex inheritance of text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2914
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2915 Self-inserting characters normally take on the same properties as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2916 preceding character. This is called @dfn{inheritance} of properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2917
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2918 In a Lisp program, you can do insertion with inheritance or without,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2919 depending on your choice of insertion primitive. The ordinary text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2920 insertion functions such as @code{insert} do not inherit any properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2921 They insert text with precisely the properties of the string being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2922 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
2923 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
2924 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
2925 section. Self-inserting characters inherit properties because they work
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2926 using these primitives.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2927
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2928 When you do insertion with inheritance, @emph{which} properties are
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2929 inherited, and from where, depends on which properties are @dfn{sticky}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2930 Insertion after a character inherits those of its properties that are
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2931 @dfn{rear-sticky}. Insertion before a character inherits those of its
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2932 properties that are @dfn{front-sticky}. When both sides offer different
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2933 sticky values for the same property, the previous character's value
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2934 takes precedence.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2935
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2936 By default, a text property is rear-sticky but not front-sticky; thus,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2937 the default is to inherit all the properties of the preceding character,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2938 and nothing from the following character.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2939
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2940 You can control the stickiness of various text properties with two
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2941 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2942 and with the variable @code{text-property-default-nonsticky}. You can
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2943 use the variable to specify a different default for a given property.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2944 You can use those two text properties to make any specific properties
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2945 sticky or nonsticky in any particular part of the text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2946
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2947 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
2948 its properties are front-sticky. If the @code{front-sticky} property is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2949 a list, then the sticky properties of the character are those whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2950 names are in the list. For example, if a character has a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2951 @code{front-sticky} property whose value is @code{(face read-only)},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2952 then insertion before the character can inherit its @code{face} property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2953 and its @code{read-only} property, but no others.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2954
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2955 The @code{rear-nonsticky} property works the opposite way. Most
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2956 properties are rear-sticky by default, so the @code{rear-nonsticky}
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2957 property says which properties are @emph{not} rear-sticky. If a
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2958 character's @code{rear-nonsticky} property is @code{t}, then none of its
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2959 properties are rear-sticky. If the @code{rear-nonsticky} property is a
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2960 list, properties are rear-sticky @emph{unless} their names are in the
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
2961 list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2962
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2963 @defvar text-property-default-nonsticky
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2964 @tindex text-property-default-nonsticky
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2965 This variable holds an alist which defines the default rear-stickiness
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2966 of various text properties. Each element has the form
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2967 @code{(@var{property} . @var{nonstickiness})}, and it defines the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2968 stickiness of a particular text property, @var{property}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2969
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2970 If @var{nonstickiness} is non-@code{nil}, this means that the property
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2971 @var{property} is rear-nonsticky by default. Since all properties are
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2972 front-nonsticky by default, this makes @var{property} nonsticky in both
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2973 directions by default.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2974
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2975 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
47475
ee41d5989edf Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 45750
diff changeset
2976 used, take precedence over the default @var{nonstickiness} specified in
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2977 @code{text-property-default-nonsticky}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
2978 @end defvar
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2979
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2980 Here are the functions that insert text with inheritance of properties:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2981
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2982 @defun insert-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2983 Insert the strings @var{strings}, just like the function @code{insert},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2984 but inherit any sticky properties from the adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2985 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2986
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2987 @defun insert-before-markers-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2988 Insert the strings @var{strings}, just like the function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2989 @code{insert-before-markers}, but inherit any sticky properties from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2990 adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2991 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2992
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2993 @xref{Insertion}, for the ordinary insertion functions which do not
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2994 inherit.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2995
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2996 @node Saving Properties
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2997 @subsection Saving Text Properties in Files
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2998 @cindex text properties in files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2999 @cindex saving text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3000
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3001 You can save text properties in files (along with the text itself),
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3002 and restore the same text properties when visiting or inserting the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3003 files, using these two hooks:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3004
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3005 @defvar write-region-annotate-functions
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3006 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
3007 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
3008 being written in the file. @xref{Writing to Files}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3009
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3010 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
3011 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
3012 contents of the buffer. Instead, they should return lists indicating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3013 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
3014 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3015
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3016 Each function should return a list of elements of the form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3017 @code{(@var{position} . @var{string})}, where @var{position} is an
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3018 integer specifying the relative position within the text to be written,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3019 and @var{string} is the annotation to add there.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3020
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3021 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
3022 increasing order by @var{position}. If there is more than one function,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3023 @code{write-region} merges the lists destructively into one sorted list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3024
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3025 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
3026 file, it intermixes the specified annotations at the corresponding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3027 positions. All this takes place without modifying the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3028 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3029
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3030 @defvar after-insert-file-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3031 This variable holds a list of functions for @code{insert-file-contents}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3032 to call after inserting a file's contents. These functions should scan
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3033 the inserted text for annotations, and convert them to the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3034 properties they stand for.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3035
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3036 Each function receives one argument, the length of the inserted text;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3037 point indicates the start of that text. The function should scan that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3038 text for annotations, delete them, and create the text properties that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3039 the annotations specify. The function should return the updated length
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3040 of the inserted text, as it stands after those changes. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3041 returned by one function becomes the argument to the next function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3042
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3043 These functions should always return with point at the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3044 the inserted text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3045
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3046 The intended use of @code{after-insert-file-functions} is for converting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3047 some sort of textual annotations into actual text properties. But other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3048 uses may be possible.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3049 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3050
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3051 We invite users to write Lisp programs to store and retrieve text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3052 properties in files, using these hooks, and thus to experiment with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3053 various data formats and find good ones. Eventually we hope users
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3054 will produce good, general extensions we can install in Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3055
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3056 We suggest not trying to handle arbitrary Lisp objects as text property
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3057 names or values---because a program that general is probably difficult
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3058 to write, and slow. Instead, choose a set of possible data types that
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3059 are reasonably flexible, and not too hard to encode.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3060
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3061 @xref{Format Conversion}, for a related feature.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3062
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3063 @c ??? In next edition, merge this info Format Conversion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3064
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3065 @node Lazy Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3066 @subsection Lazy Computation of Text Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3067
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3068 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
3069 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
3070 when and if something depends on them.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3071
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3072 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
3073 properties is @code{buffer-substring}. Before examining the properties,
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3074 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
3075
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3076 @defvar buffer-access-fontify-functions
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3077 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
3078 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
3079 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
3080 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
3081 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
3082 buffer.)
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3083 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3084
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3085 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
3086 functions, since it ignores text properties anyway.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3087
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3088 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
3089 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
3090 @code{buffer-access-fontified-property}.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3091
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3092 @defvar buffer-access-fontified-property
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3093 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
3094 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
3095 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
3096 computed.''
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3097
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3098 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
3099 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
3100 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
3101 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
3102 just copies the properties they already have.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3103
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3104 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
3105 @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
3106 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
3107 being called over and over for the same text.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3108 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3109
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3110 @node Clickable Text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3111 @subsection Defining Clickable Text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3112 @cindex clickable text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3113
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3114 There are two ways to set up @dfn{clickable text} in a buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3115 There are typically two parts of this: to make the text highlight
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3116 when the mouse is over it, and to make a mouse button do something
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3117 when you click it on that part of the text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3118
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3119 Highlighting is done with the @code{mouse-face} text property.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3120 Here is an example of how Dired does it:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3121
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3122 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3123 (condition-case nil
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3124 (if (dired-move-to-filename)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3125 (put-text-property (point)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3126 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3127 (dired-move-to-end-of-filename)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3128 (point))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3129 'mouse-face 'highlight))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3130 (error nil))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3131 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3132
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3133 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3134 The first two arguments to @code{put-text-property} specify the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3135 beginning and end of the text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3136
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3137 The usual way to make the mouse do something when you click it
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3138 on this text is to define @code{mouse-2} in the major mode's
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3139 keymap. The job of checking whether the click was on clickable text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3140 is done by the command definition. Here is how Dired does it:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3141
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3142 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3143 (defun dired-mouse-find-file-other-window (event)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3144 "In dired, visit the file or directory name you click on."
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3145 (interactive "e")
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3146 (let (file)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3147 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3148 (set-buffer (window-buffer (posn-window (event-end event))))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3149 (save-excursion
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3150 (goto-char (posn-point (event-end event)))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3151 (setq file (dired-get-filename))))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3152 (select-window (posn-window (event-end event)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3153 (find-file-other-window (file-name-sans-versions file t))))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3154 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3155
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3156 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3157 The reason for the outer @code{save-excursion} construct is to avoid
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3158 changing the current buffer; the reason for the inner one is to avoid
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3159 permanently altering point in the buffer you click on. In this case,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3160 Dired uses the function @code{dired-get-filename} to determine which
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3161 file to visit, based on the position found in the event.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3162
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3163 Instead of defining a mouse command for the major mode, you can define
31586
b51dba45cbe7 (Clickable Text): Fix example.
Dave Love <fx@gnu.org>
parents: 31372
diff changeset
3164 a key binding for the clickable text itself, using the @code{keymap}
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
3165 text property:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3166
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3167 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3168 (let ((map (make-sparse-keymap)))
31586
b51dba45cbe7 (Clickable Text): Fix example.
Dave Love <fx@gnu.org>
parents: 31372
diff changeset
3169 (define-key map [mouse-2] 'operate-this-button)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3170 (put-text-property (point)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3171 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3172 (dired-move-to-end-of-filename)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3173 (point))
31586
b51dba45cbe7 (Clickable Text): Fix example.
Dave Love <fx@gnu.org>
parents: 31372
diff changeset
3174 'keymap map))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3175 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3176
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3177 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3178 This method makes it possible to define different commands for various
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3179 clickable pieces of text. Also, the major mode definition (or the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3180 global definition) remains available for the rest of the text in the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3181 buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3182
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3183 @node Fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3184 @subsection Defining and Using Fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3185 @cindex fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3186
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3187 A field is a range of consecutive characters in the buffer that are
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3188 identified by having the same value (comparing with @code{eq}) of the
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3189 @code{field} property (either a text-property or an overlay property).
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3190 This section describes special functions that are available for
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3191 operating on fields.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3192
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3193 You specify a field with a buffer position, @var{pos}. We think of
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3194 each field as containing a range of buffer positions, so the position
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3195 you specify stands for the field containing that position.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3196
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3197 When the characters before and after @var{pos} are part of the same
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3198 field, there is no doubt which field contains @var{pos}: the one those
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3199 characters both belong to. When @var{pos} is at a boundary between
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3200 fields, which field it belongs to depends on the stickiness of the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3201 @code{field} properties of the two surrounding characters (@pxref{Sticky
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3202 Properties}). The field whose property would be inherited by text
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3203 inserted at @var{pos} is the field that contains @var{pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3204
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3205 There is an anomalous case where newly inserted text at @var{pos}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3206 would not inherit the @code{field} property from either side. This
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3207 happens if the previous character's @code{field} property is not
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3208 rear-sticky, and the following character's @code{field} property is not
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3209 front-sticky. In this case, @var{pos} belongs to neither the preceding
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3210 field nor the following field; the field functions treat it as belonging
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3211 to an empty field whose beginning and end are both at @var{pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3212
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3213 In all of these functions, if @var{pos} is omitted or @code{nil}, the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3214 value of point is used by default.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3215
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3216 @defun field-beginning &optional pos escape-from-edge limit
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3217 @tindex field-beginning
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3218 This function returns the beginning of the field specified by @var{pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3219
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3220 If @var{pos} is at the beginning of its field, and
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3221 @var{escape-from-edge} is non-@code{nil}, then the return value is
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3222 always the beginning of the preceding field that @emph{ends} at @var{pos},
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3223 regardless of the stickiness of the @code{field} properties around
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3224 @var{pos}.
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3225
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3226 If @var{limit} is non-@code{nil}, it is a buffer position; if the
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3227 beginning of the field is before @var{limit}, then @var{limit} will be
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3228 returned instead.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3229 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3230
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3231 @defun field-end &optional pos escape-from-edge limit
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3232 @tindex field-end
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3233 This function returns the end of the field specified by @var{pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3234
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3235 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3236 non-@code{nil}, then the return value is always the end of the following
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3237 field that @emph{begins} at @var{pos}, regardless of the stickiness of
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3238 the @code{field} properties around @var{pos}.
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3239
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3240 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3241 of the field is after @var{limit}, then @var{limit} will be returned
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3242 instead.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3243 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3244
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3245 @defun field-string &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3246 @tindex field-string
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3247 This function returns the contents of the field specified by @var{pos},
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3248 as a string.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3249 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3250
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3251 @defun field-string-no-properties &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3252 @tindex field-string-no-properties
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3253 This function returns the contents of the field specified by @var{pos},
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3254 as a string, discarding text properties.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3255 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3256
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3257 @defun delete-field &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3258 @tindex delete-field
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3259 This function deletes the text of the field specified by @var{pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3260 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3261
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3262 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3263 @tindex constrain-to-field
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3264 This function ``constrains'' @var{new-pos} to the field that
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3265 @var{old-pos} belongs to---in other words, it returns the position
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3266 closest to @var{new-pos} that is in the same field as @var{old-pos}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3267
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3268 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3269 the value of point instead, and moves point to the resulting position.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3270
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3271 If @var{old-pos} is at the boundary of two fields, then the acceptable
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3272 positions for @var{new-pos} depend on the value of the optional argument
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3273 @var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3274 @var{new-pos} is constrained to the field that has the same @code{field}
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3275 property (either a text-property or an overlay property) that new
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3276 characters inserted at @var{old-pos} would get. (This depends on the
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3277 stickiness of the @code{field} property for the characters before and
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3278 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3279 @var{new-pos} is constrained to the union of the two adjacent fields.
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3280 Additionally, if two fields are separated by another field with the
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3281 special value @code{boundary}, then any point within this special field
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3282 is also considered to be ``on the boundary.''
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3283
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3284 If the optional argument @var{only-in-line} is non-@code{nil}, and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3285 constraining @var{new-pos} in the usual way would move it to a different
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3286 line, @var{new-pos} is returned unconstrained. This used in commands
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3287 that move by line, such as @code{next-line} and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3288 @code{beginning-of-line}, so that they respect field boundaries only in
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3289 the case where they can still move to the right line.
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3290
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3291 If the optional argument @var{inhibit-capture-property} is
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3292 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3293 name, then any field boundaries are ignored.
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3294
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3295 You can cause @code{constrain-to-field} to ignore all field boundaries
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3296 (and so never constrain anything) by binding the variable
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3297 @code{inhibit-field-text-motion} to a non-nil value.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3298 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3299
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3300 @node Not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3301 @subsection Why Text Properties are not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3302 @cindex intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3303
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3304 Some editors that support adding attributes to text in the buffer do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3305 so by letting the user specify ``intervals'' within the text, and adding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3306 the properties to the intervals. Those editors permit the user or the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3307 programmer to determine where individual intervals start and end. We
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3308 deliberately provided a different sort of interface in Emacs Lisp to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3309 avoid certain paradoxical behavior associated with text modification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3310
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3311 If the actual subdivision into intervals is meaningful, that means you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3312 can distinguish between a buffer that is just one interval with a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3313 certain property, and a buffer containing the same text subdivided into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3314 two intervals, both of which have that property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3315
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3316 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
3317 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
3318 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
3319 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
3320 same properties. Thus, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3321 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3322
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3323 Suppose we ``fix'' this problem by coalescing the two intervals when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3324 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
3325 single interval. But suppose instead that we have two adjacent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3326 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
3327 and yank it back. The same interval-coalescence feature that rescues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3328 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
3329 one interval. One again, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3330 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3331
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3332 Insertion of text at the border between intervals also raises
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3333 questions that have no satisfactory answer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3334
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3335 However, it is easy to arrange for editing to behave consistently for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3336 questions of the form, ``What are the properties of this character?''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3337 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
3338 not implemented asking questions about where intervals start or end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3339
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3340 In practice, you can usually use the text property search functions in
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3341 place of explicit interval boundaries. You can think of them as finding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3342 the boundaries of intervals, assuming that intervals are always
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3343 coalesced whenever possible. @xref{Property Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3344
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3345 Emacs also provides explicit intervals as a presentation feature; see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3346 @ref{Overlays}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3347
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3348 @node Substitution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3349 @section Substituting for a Character Code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3350
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3351 The following functions replace characters within a specified region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3352 based on their character codes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3353
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3354 @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
3355 @cindex replace characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3356 This function replaces all occurrences of the character @var{old-char}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3357 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
3358 defined by @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3359
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3360 @cindex undo avoidance
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3361 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
3362 not record the change for undo and does not mark the buffer as modified.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3363 This was useful for controlling the old selective display feature
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3364 (@pxref{Selective Display}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3365
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3366 @code{subst-char-in-region} does not move point and returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3367 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3368
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3369 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3370 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3371 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3372 This is the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3373 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3374 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3375
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3376 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3377 (subst-char-in-region 1 20 ?i ?X)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3378 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3379
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3380 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3381 ThXs Xs the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3382 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3383 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3384 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3385 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3386
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3387 @defun translate-region start end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3388 This function applies a translation table to the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3389 buffer between positions @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3391 The translation table @var{table} is a string; @code{(aref @var{table}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3392 @var{ochar})} gives the translated character corresponding to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3393 @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
3394 characters with codes larger than the length of @var{table} are not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3395 altered by the translation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3396
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3397 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
3398 characters that were actually changed by the translation. This does
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
3399 not count characters that were mapped into themselves in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3400 translation table.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3401 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3402
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3403 @node Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3404 @section Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3405 @cindex registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3406
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3407 A register is a sort of variable used in Emacs editing that can hold a
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3408 variety of different kinds of values. Each register is named by a
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3409 single character. All @sc{ascii} characters and their meta variants
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3410 (but with the exception of @kbd{C-g}) can be used to name registers.
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3411 Thus, there are 255 possible registers. A register is designated in
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3412 Emacs Lisp by the character that is its name.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3413
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3414 @defvar register-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3415 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
3416 @var{contents})}. Normally, there is one element for each Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3417 register that has been used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3419 The object @var{name} is a character (an integer) identifying the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3420 register.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3421 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3422
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3423 The @var{contents} of a register can have several possible types:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3424
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3425 @table @asis
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3426 @item a number
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3427 A number stands for itself. If @code{insert-register} finds a number
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3428 in the register, it converts the number to decimal.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3429
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3430 @item a marker
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3431 A marker represents a buffer position to jump to.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3432
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3433 @item a string
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3434 A string is text saved in the register.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3435
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3436 @item a rectangle
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3437 A rectangle is represented by a list of strings.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3438
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3439 @item @code{(@var{window-configuration} @var{position})}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3440 This represents a window configuration to restore in one frame, and a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3441 position to jump to in the current buffer.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3442
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3443 @item @code{(@var{frame-configuration} @var{position})}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3444 This represents a frame configuration to restore, and a position
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3445 to jump to in the current buffer.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3446
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3447 @item (file @var{filename})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3448 This represents a file to visit; jumping to this value visits file
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3449 @var{filename}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3450
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3451 @item (file-query @var{filename} @var{position})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3452 This represents a file to visit and a position in it; jumping to this
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3453 value visits file @var{filename} and goes to buffer position
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3454 @var{position}. Restoring this type of position asks the user for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3455 confirmation first.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3456 @end table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3457
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3458 The functions in this section return unpredictable values unless
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3459 otherwise stated.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3460
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3461 @defun get-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3462 This function returns the contents of the register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3463 @var{reg}, or @code{nil} if it has no contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3464 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3465
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3466 @defun set-register reg value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3467 This function sets the contents of register @var{reg} to @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3468 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
3469 expect only certain data types. The return value is @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3470 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3472 @deffn Command view-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3473 This command displays what is contained in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3474 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3475
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3476 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3477 @deffn Command point-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3478 This command stores both the current location of point and the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3479 buffer in register @var{reg} as a marker.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3480 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3481
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3482 @deffn Command jump-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3483 @deffnx Command register-to-point reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3484 @comment !!SourceFile register.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3485 This command restores the status recorded in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3486
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3487 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
3488 the marker. Since both the buffer and the location within the buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3489 are stored by the @code{point-to-register} function, this command can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3490 switch you to another buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3491
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3492 If @var{reg} contains a window configuration or a frame configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3493 @code{jump-to-register} restores that configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3494 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3495 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3496
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3497 @deffn Command insert-register reg &optional beforep
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3498 This command inserts contents of register @var{reg} into the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3499 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3500
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3501 Normally, this command puts point before the inserted text, and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3502 mark after it. However, if the optional second argument @var{beforep}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3503 is non-@code{nil}, it puts the mark before and point after.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3504 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
3505 function interactively by supplying any prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3506
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3507 If the register contains a rectangle, then the rectangle is inserted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3508 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
3509 in the current line and underneath it on successive lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3510
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3511 If the register contains something other than saved text (a string) or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3512 a rectangle (a list), currently useless things happen. This may be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3513 changed in the future.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3514 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3515
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3516 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3517 @deffn Command copy-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3518 This command copies the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3519 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
3520 the region from the buffer after copying it into the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3521 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3522
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3523 @deffn Command prepend-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3524 This command prepends the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3525 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
3526 the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3527 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3528
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3529 @deffn Command append-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3530 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
3531 text already in register @var{reg}. If @var{delete-flag} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3532 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
3533 to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3534 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3535
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3536 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3537 This command copies a rectangular region from @var{start} to @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3538 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
3539 deletes the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3540 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3541
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3542 @deffn Command window-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3543 This function stores the window configuration of the selected frame in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3544 register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3545 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3546
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3547 @deffn Command frame-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3548 This function stores the current frame configuration in register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3549 @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3550 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3551 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3552
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3553 @node Transposition
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3554 @section Transposition of Text
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3555
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3556 This subroutine is used by the transposition commands.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3557
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3558 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3559 This function exchanges two nonoverlapping portions of the buffer.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3560 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
3561 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
3562 other portion.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3563
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3564 Normally, @code{transpose-regions} relocates markers with the transposed
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3565 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
3566 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
3567 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
3568 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
3569 all markers unrelocated.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3570 @end defun
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3571
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3572 @node Base 64
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3573 @section Base 64 Encoding
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3574 @cindex base 64 encoding
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3575
39168
0317f0f05c37 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 38581
diff changeset
3576 Base 64 code is used in email to encode a sequence of 8-bit bytes as
0317f0f05c37 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 38581
diff changeset
3577 a longer sequence of @sc{ascii} graphic characters. It is defined in
39208
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3578 Internet RFC@footnote{
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3579 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3580 Internet informational document describing a standard. RFCs are
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3581 usually written by technical experts acting on their own initiative,
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3582 and are traditionally written in a pragmatic, experience-driven
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3583 manner.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3584 }2045. This section describes the functions for
39168
0317f0f05c37 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 38581
diff changeset
3585 converting to and from this code.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3586
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3587 @defun base64-encode-region beg end &optional no-line-break
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3588 @tindex base64-encode-region
33911
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3589 This function converts the region from @var{beg} to @var{end} into base
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3590 64 code. It returns the length of the encoded text. An error is
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3591 signaled if a character in the region is multibyte, i.e.@: in a
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3592 multibyte buffer the region must contain only characters from the
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3593 charsets @code{ascii}, @code{eight-bit-control} and
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3594 @code{eight-bit-graphic}.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3595
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3596 Normally, this function inserts newline characters into the encoded
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3597 text, to avoid overlong lines. However, if the optional argument
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3598 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3599 the output is just one long line.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3600 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3601
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3602 @defun base64-encode-string string &optional no-line-break
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3603 @tindex base64-encode-string
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3604 This function converts the string @var{string} into base 64 code. It
33911
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3605 returns a string containing the encoded text. As for
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3606 @code{base64-encode-region}, an error is signaled if a character in the
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
3607 string is multibyte.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3608
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3609 Normally, this function inserts newline characters into the encoded
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3610 text, to avoid overlong lines. However, if the optional argument
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3611 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3612 the result string is just one long line.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3613 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3614
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3615 @defun base64-decode-region beg end
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3616 @tindex base64-decode-region
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3617 This function converts the region from @var{beg} to @var{end} from base
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3618 64 code into the corresponding decoded text. It returns the length of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3619 the decoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3620
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3621 The decoding functions ignore newline characters in the encoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3622 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3623
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3624 @defun base64-decode-string string
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3625 @tindex base64-decode-string
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3626 This function converts the string @var{string} from base 64 code into
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3627 the corresponding decoded text. It returns a string containing the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3628 decoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3629
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3630 The decoding functions ignore newline characters in the encoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3631 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
3632
39208
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3633 @node MD5 Checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3634 @section MD5 Checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3635 @cindex MD5 checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3636 @cindex message digest computation
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3637
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3638 MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3639 ``fingerprints'' of a document or program. They are used to verify
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3640 that you have an exact and unaltered copy of the data. The algorithm
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3641 to calculate the MD5 message digest is defined in Internet
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3642 RFC@footnote{
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3643 For an explanation of what is an RFC, see the footnote in @ref{Base
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3644 64}.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3645 }1321. This section describes the Emacs facilities for computing
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3646 message digests.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3647
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3648 @defun md5 object &optional start end coding-system noerror
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3649 This function returns the MD5 message digest of @var{object}, which
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3650 should be a buffer or a string.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3651
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3652 The two optional arguments @var{start} and @var{end} are character
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3653 positions specifying the portion of @var{object} to compute the
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3654 message digest for. If they are @code{nil} or omitted, the digest is
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3655 computed for the whole of @var{object}.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3656
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3657 The function @code{md5} does not compute the message digest directly
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3658 from the internal Emacs representation of the text (@pxref{Text
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3659 Representations}). Instead, it encodes the text using a coding
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3660 system, and computes the message digest from the encoded text. The
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3661 optional fourth argument @var{coding-system} specifies which coding
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3662 system to use for encoding the text. It should be the same coding
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3663 system that you used to read the text, or that you used or will use
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3664 when saving or sending the text. @xref{Coding Systems}, for more
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3665 information about coding systems.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3666
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3667 If @var{coding-system} is @code{nil} or omitted, the default depends
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3668 on @var{object}. If @var{object} is a buffer, the default for
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3669 @var{coding-system} is whatever coding system would be chosen by
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3670 default for writing this text into a file. If @var{object} is a
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3671 string, the user's most preferred coding system (@pxref{Recognize
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3672 Coding, prefer-coding-system, the description of
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3673 @code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3674
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3675 Normally, @code{md5} signals an error if the text can't be encoded
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3676 using the specified or chosen coding system. However, if
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3677 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3678 coding instead.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3679 @end defun
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
3680
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3681 @node Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3682 @section Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3683 @cindex change hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3684 @cindex hooks for text changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3685
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3686 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
3687 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
3688 See also @ref{Special Properties}, for how to detect changes to specific
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3689 parts of the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3690
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3691 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
3692 data if they do anything that uses regular expressions; otherwise, they
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3693 will interfere in bizarre ways with the editing operations that call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3694 them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3695
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3696 @defvar before-change-functions
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3697 This variable holds a list of functions to call before any buffer
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3698 modification. Each function gets two arguments, the beginning and end
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3699 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
3700 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
3701 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3702
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3703 @defvar after-change-functions
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3704 This variable holds a list of functions to call after any buffer
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3705 modification. Each function receives three arguments: the beginning and
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3706 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
3707 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
3708 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
3709
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
3710 The length of the old text is the difference between the buffer positions
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
3711 before and after that text as it was before the change. As for the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
3712 changed text, its length is simply the difference between the first two
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
3713 arguments.
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3714 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3715
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
3716 @defmac combine-after-change-calls body...
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3717 The macro executes @var{body} normally, but arranges to call the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3718 after-change functions just once for a series of several changes---if
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3719 that seems safe.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3720
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3721 If a program makes several text changes in the same area of the buffer,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3722 using the macro @code{combine-after-change-calls} around that part of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3723 the program can make it run considerably faster when after-change hooks
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3724 are in use. When the after-change hooks are ultimately called, the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3725 arguments specify a portion of the buffer including all of the changes
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3726 made within the @code{combine-after-change-calls} body.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3727
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3728 @strong{Warning:} You must not alter the values of
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3729 @code{after-change-functions} within
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3730 the body of a @code{combine-after-change-calls} form.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3731
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3732 @strong{Note:} If the changes you combine occur in widely scattered
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3733 parts of the buffer, this will still work, but it is not advisable,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3734 because it may lead to inefficient behavior for some change hook
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3735 functions.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3736 @end defmac
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3737
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3738 The two variables above are temporarily bound to @code{nil} during the
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3739 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
3740 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
3741 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
3742 these functions, make it bind these variables back to their usual
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3743 values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3744
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3745 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
3746 have a function in @code{after-change-functions} or
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3747 @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
3748 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
3749 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
3750 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
3751 to call. Here is an example:
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3752
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3753 @example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3754 (setq my-own-after-change-functions nil)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3755 (defun indirect-after-change-function (beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3756 (let ((list my-own-after-change-functions))
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3757 (while list
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3758 (funcall (car list) beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3759 (setq list (cdr list)))))
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3760
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3761 @group
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3762 (add-hooks 'after-change-functions
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3763 'indirect-after-change-function)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3764 @end group
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3765 @end example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3766
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3767 @defvar first-change-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3768 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
3769 that was previously in the unmodified state.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3770 @end defvar
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3771
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3772 @defvar inhibit-modification-hooks
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3773 @tindex inhibit-modification-hooks
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3774 If this variable is non-@code{nil}, all of the change hooks are
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3775 disabled; none of them run. This affects all the hook variables
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3776 described above in this section, as well as the hooks attached to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3777 certain special text properties (@pxref{Special Properties}) and overlay
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3778 properties (@pxref{Overlay Properties}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3779
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3780 This variable is available starting in Emacs 21.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3781 @end defvar