annotate lispref/text.texi @ 78464:7819402a9963

Use window-full-width-p instead of comparing frame-width and window-width.
author Martin Rudalics <rudalics@gmx.at>
date Wed, 08 Aug 2007 05:51:36 +0000
parents 602257788b4a
children b86e73d7c635 7edf1ae10375
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.
64889
e836425ee789 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 63950
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
75348
3d45362f1d38 Add 2007 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 72975
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007 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.
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
60 * MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
61 * Atomic Changes:: Installing several buffer changes "atomically".
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 * Change Hooks:: Supplying functions to be run when text is changed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @node Near Point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @section Examining Text Near Point
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75348
diff changeset
67 @cindex text near point
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 Many functions are provided to look at the characters around point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 Several simple functions are described here. See also @code{looking-at}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 in @ref{Regexp Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
73 In the following four functions, ``beginning'' or ``end'' of buffer
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
74 refers to the beginning or end of the accessible portion.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
75
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
76 @defun char-after &optional position
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 This function returns the character in the current buffer at (i.e.,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 immediately after) position @var{position}. If @var{position} is out of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 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
80 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
81 @var{position} is point.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 In the following example, assume that the first character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 buffer is @samp{@@}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 (char-to-string (char-after 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 @result{} "@@"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
94 @defun char-before &optional position
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
95 This function returns the character in the current buffer immediately
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
96 before position @var{position}. If @var{position} is out of range for
50467
cb9a2b0620a3 (Near Point): Fix nonsense in char-before.
Richard M. Stallman <rms@gnu.org>
parents: 49677
diff changeset
97 this purpose, either at or before the beginning of the buffer, or beyond
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
98 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
99 @var{position} is point.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
100 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
101
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @defun following-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 This function returns the character following point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 buffer. This is similar to @code{(char-after (point))}. However, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 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
106
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
107 Remember that point is always between characters, and the cursor
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
108 normally appears over the character following point. Therefore, the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
109 character returned by @code{following-char} is the character the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 cursor is over.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 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
113
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 Gentlemen may cry ``Pea@point{}ce! Peace!,''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 but there is no peace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 (char-to-string (preceding-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @result{} "a"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 (char-to-string (following-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @result{} "c"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @defun preceding-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 This function returns the character preceding point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 buffer. See above, under @code{following-char}, for an example. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 point is at the beginning of the buffer, @code{preceding-char} returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @defun bobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 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
140 buffer. If narrowing is in effect, this means the beginning of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 accessible portion of the text. See also @code{point-min} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @ref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @defun eobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 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
147 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
148 the text. See also @code{point-max} in @xref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @defun bolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 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
153 @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
154 portion) always counts as the beginning of a line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @defun eolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 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
159 end of the buffer (or of its accessible portion) is always considered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 the end of a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @node Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @section Examining Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165
54041
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
166 This section describes functions that allow a Lisp program to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 convert any portion of the text in the buffer into a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 @defun buffer-substring start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 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
171 region defined by positions @var{start} and @var{end} in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 buffer. If the arguments are not positions in the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 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
177 arguments can be given in either order. But most often the smaller
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 argument is written first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
180 Here's an example which assumes Font-Lock mode is not enabled:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
181
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 (buffer-substring 1 10)
65321
cea6d5596fa2 (Buffer Contents): Use "\n" in examples' result strings.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
192 @result{} "This is t"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 (buffer-substring (point-max) 10)
65321
cea6d5596fa2 (Buffer Contents): Use "\n" in examples' result strings.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
196 @result{} "he contents of buffer foo\n"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end example
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
199
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
200 If the text being copied has any text properties, these are copied into
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
201 the string along with the characters they belong to. @xref{Text
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
202 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
203 their properties are ignored, not copied.
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
204
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
205 For example, if Font-Lock mode is enabled, you might get results like
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
206 these:
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
207
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
208 @example
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
209 @group
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
210 (buffer-substring 1 10)
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
211 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
212 @end group
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
213 @end example
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215
13109
acb0ab49f4e7 Fix name of buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 12775
diff changeset
216 @defun buffer-substring-no-properties start end
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
217 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
218 properties, just the characters themselves. @xref{Text Properties}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
219 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
220
69903
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
221 @defun filter-buffer-substring start end &optional delete noprops
61116
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
222 This function passes the buffer text between @var{start} and @var{end}
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
223 through the filter functions specified by the variable
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
224 @code{buffer-substring-filters}, and returns the value from the last
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
225 filter function. If @code{buffer-substring-filters} is @code{nil},
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
226 the value is the unaltered text from the buffer, what
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
227 @code{buffer-substring} would return.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
228
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
229 If @var{delete} is non-@code{nil}, this function deletes the text
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
230 between @var{start} and @var{end} after copying it, like
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
231 @code{delete-and-extract-region}.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
232
69903
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
233 If @var{noprops} is non-@code{nil}, the final string returned does not
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
234 include text properties, while the string passed through the filters
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
235 still includes text properties from the buffer text.
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
236
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
237 Lisp code should use this function instead of @code{buffer-substring},
5b6c4153d145 (Buffer Contents): Add NOPROPS arg to filter-buffer-substring.
Kim F. Storm <storm@cua.dk>
parents: 69578
diff changeset
238 @code{buffer-substring-no-properties},
61116
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
239 or @code{delete-and-extract-region} when copying into user-accessible
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
240 data structures such as the kill-ring, X clipboard, and registers.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
241 Major and minor modes can add functions to
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
242 @code{buffer-substring-filters} to alter such text as it is copied out
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
243 of the buffer.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
244 @end defun
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
245
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
246 @defvar buffer-substring-filters
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
247 This variable should be a list of functions that accept a single
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
248 argument, a string, and return a string.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
249 @code{filter-buffer-substring} passes the buffer substring to the
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
250 first function in this list, and the return value of each function is
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
251 passed to the next function. The return value of the last function is
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
252 used as the return value of @code{filter-buffer-substring}.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
253
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
254 As a special convention, point is set to the start of the buffer text
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
255 being operated on (i.e., the @var{start} argument for
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
256 @code{filter-buffer-substring}) before these functions are called.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
257
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
258 If this variable is @code{nil}, no filtering is performed.
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
259 @end defvar
171f1eda0401 (Buffer Contents): Add filter-buffer-substring and buffer-substring-filters.
Richard M. Stallman <rms@gnu.org>
parents: 60687
diff changeset
260
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @defun buffer-string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
262 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
263 the current buffer as a string. It is equivalent to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
264
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
265 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
266 (buffer-substring (point-min) (point-max))
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
267 @end example
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 This is the contents of buffer foo
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 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 (buffer-string)
65321
cea6d5596fa2 (Buffer Contents): Use "\n" in examples' result strings.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
277 @result{} "This is the contents of buffer foo\n"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281
51702
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
282 @defun current-word &optional strict really-word
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
283 This function returns the symbol (or word) at or near point, as a string.
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
284 The return value includes no text properties.
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
285
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
286 If the optional argument @var{really-word} is non-@code{nil}, it finds a
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
287 word; otherwise, it finds a symbol (which includes both word
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
288 characters and symbol constituent characters).
51702
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
289
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
290 If the optional argument @var{strict} is non-@code{nil}, then point
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
291 must be in or next to the symbol or word---if no symbol or word is
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
292 there, the function returns @code{nil}. Otherwise, a nearby symbol or
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
293 word on the same line is acceptable.
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
294 @end defun
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
295
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
296 @defun thing-at-point thing
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
297 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
298
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
299 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
300 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
301 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
302 @code{whitespace}, @code{line}, @code{page}, and others.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
303
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
304 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
305 ---------- Buffer: foo ----------
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
306 Gentlemen may cry ``Pea@point{}ce! Peace!,''
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
307 but there is no peace.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
308 ---------- Buffer: foo ----------
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
309
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
310 (thing-at-point 'word)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
311 @result{} "Peace"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
312 (thing-at-point 'line)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
313 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
314 (thing-at-point 'whitespace)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
315 @result{} nil
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
316 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
317 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
318
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @node Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @section Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @cindex comparing buffer text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 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
324 copying them into strings first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 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
328 different buffers. The first three arguments specify one substring,
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
329 giving a buffer (or a buffer name) and two positions within the
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
330 buffer. The last three arguments specify the other substring in the
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
331 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
332 both to stand for the current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 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
335 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
336 the result is one plus the index of the first differing characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 within the substrings.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 This function ignores case when comparing characters
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
340 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
341 text properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 Suppose the current buffer contains the text @samp{foobarbar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 haha!rara!}; then in this example the two substrings are @samp{rbar }
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 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
346 at the second character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
349 (compare-buffer-substrings nil 6 11 nil 16 21)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @result{} 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @node Insertion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
355 @section Inserting Text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @cindex insertion of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @cindex text insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
359 @cindex insertion before point
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
360 @cindex before point, insertion
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 @dfn{Insertion} means adding new text to a buffer. The inserted text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 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
363 after point. Some insertion functions leave point before the inserted
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
364 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
365 insertion @dfn{after point} and the latter insertion @dfn{before point}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 Insertion relocates markers that point at positions after the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 insertion point, so that they stay with the surrounding text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 (@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
370 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
371 insertion type (@pxref{Marker Insertion Types}). Certain special
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
372 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
373 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
374 type.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 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
377 read-only or if they insert within read-only text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
379 These functions copy text characters from strings and buffers along
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
380 with their properties. The inserted characters have exactly the same
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
381 properties as the characters they were copied from. By contrast,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
382 characters specified as separate arguments, not part of a string or
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
383 buffer, inherit their text properties from the neighboring text.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
384
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
385 The insertion functions convert text from unibyte to multibyte in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
386 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
387 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
388 unibyte character codes 128 through 255 to multibyte characters, not
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
389 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
390 Representations}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
391
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @defun insert &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 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
394 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
395 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
396 @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
397 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @defun insert-before-markers &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 This function inserts the strings and/or characters @var{args} into the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 current buffer, at point, moving point forward. An error is signaled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 unless all @var{args} are either strings or characters. The value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 This function is unlike the other insertion functions in that it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 relocates markers initially pointing at the insertion point, to point
54041
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
407 after the inserted text. If an overlay begins at the insertion point,
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
408 the inserted text falls outside the overlay; if a nonempty overlay
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
409 ends at the insertion point, the inserted text falls inside that
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
410 overlay.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412
49677
5c2d8e3b81b4 (Insertion): Don't show COUNT argument of `insert-char' as optional.
Juanma Barranquero <lekktu@gmail.com>
parents: 49600
diff changeset
413 @defun insert-char character count &optional inherit
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 This function inserts @var{count} instances of @var{character} into the
65322
ce1b010dd1b5 (Insertion): Document precise type of `insert-char' arg COUNT.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 65321
diff changeset
415 current buffer before point. The argument @var{count} should be an
ce1b010dd1b5 (Insertion): Document precise type of `insert-char' arg COUNT.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 65321
diff changeset
416 integer, and @var{character} must be a character. The value is @code{nil}.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
417
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
418 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
419 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
420 buffer. @xref{Converting Representations}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
421
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
422 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
423 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
424 insertion point. @xref{Sticky Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @defun insert-buffer-substring from-buffer-or-name &optional start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 This function inserts a portion of buffer @var{from-buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 (which must already exist) into the current buffer before point. The
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
430 text inserted is the region between @var{start} and @var{end}. (These
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 arguments default to the beginning and end of the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 that buffer.) This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 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
435 current buffer. We assume that buffer @samp{bar} is initially empty.
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 We hold these truths to be self-evident, that all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 (insert-buffer-substring "foo" 1 20)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 ---------- Buffer: bar ----------
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
449 We hold these truth@point{}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
455 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
456 This is like @code{insert-buffer-substring} except that it does not
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
457 copy any text properties.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
458 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
459
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @xref{Sticky Properties}, for other insertion functions that inherit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
461 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
462 Whitespace inserted by indentation functions also inherits text
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
463 properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @node Commands for Insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @section User-Level Insertion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 This section describes higher-level commands for inserting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @deffn Command insert-buffer from-buffer-or-name
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
473 This command inserts the entire accessible contents of
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
474 @var{from-buffer-or-name} (which must exist) into the current buffer
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
475 after point. It leaves the mark after the inserted text. The value
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
476 is @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @deffn Command self-insert-command count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @cindex character insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @cindex self-insertion
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
482 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
483 times, before point, and returns @code{nil}. Most printing characters
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
484 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
485 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
486 it except to install it on a keymap.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 In an interactive call, @var{count} is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489
67769
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
490 Self-insertion translates the input character through
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
491 @code{translation-table-for-input}. @xref{Translation of Characters}.
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
492
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
493 This command calls @code{auto-fill-function} whenever that is
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
494 non-@code{nil} and the character inserted is in the table
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
495 @code{auto-fill-chars} (@pxref{Auto Filling}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
498 This command performs abbrev expansion if Abbrev mode is enabled and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 the inserted character does not have word-constituent
67769
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
500 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
501 responsible for calling @code{blink-paren-function} when the inserted
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
502 character has close parenthesis syntax (@pxref{Blinking}).
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
503
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
504 Do not try substituting your own definition of
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
505 @code{self-insert-command} for the standard one. The editor command
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
506 loop handles this function specially.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
509 @deffn Command newline &optional number-of-newlines
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 This command inserts newlines into the current buffer before point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 If @var{number-of-newlines} is supplied, that many newline characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 are inserted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @cindex newline and Auto Fill mode
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
515 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
516 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
517 @var{number-of-newlines} is @code{nil}. Typically what
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
518 @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
519 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
520 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
521 auto-fill if @var{number-of-newlines} is non-@code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
523 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
524 @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
525
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 The value returned is @code{nil}. In an interactive call, @var{count}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @defvar overwrite-mode
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
531 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
532 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
533 or @code{nil}. @code{overwrite-mode-textual} specifies textual
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
534 overwrite mode (treats newlines and tabs specially), and
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
535 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
536 newlines and tabs like any other characters).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @node Deletion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
540 @section Deleting Text
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75348
diff changeset
541 @cindex text deletion
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
543 @cindex deleting text vs killing
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 Deletion means removing part of the text in a buffer, without saving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 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
546 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
547 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
548 cases.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
550 All of the deletion functions operate on the current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
552 @deffn Command erase-buffer
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
553 This function deletes the entire text of the current buffer
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
554 (@emph{not} just the accessible portion), leaving it
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 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
556 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
557 @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
558 asking for any confirmation. It returns @code{nil}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
559
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 Normally, deleting a large amount of text from a buffer inhibits further
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
561 auto-saving of that buffer ``because it has shrunk.'' However,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @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
563 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
564 be compared with that of the former text.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
565 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @deffn Command delete-region start end
27654
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
568 This command deletes the text between positions @var{start} and
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
569 @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
570 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
571 Otherwise, point relocates with the surrounding text, as markers do.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573
27654
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
574 @defun delete-and-extract-region start end
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
575 This function deletes the text between positions @var{start} and
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
576 @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
577 text just deleted.
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
578
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
579 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
580 @var{start}. Otherwise, point relocates with the surrounding text, as
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
581 markers do.
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
582 @end defun
cabb1b4c4424 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
583
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @deffn Command delete-char count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 This command deletes @var{count} characters directly after point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 before point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 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
588
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 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
592 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 @deffn Command delete-backward-char count &optional killp
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
599 @cindex deleting previous char
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 This command deletes @var{count} characters directly before point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 after point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 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
603
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 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
607 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @deffn Command backward-delete-char-untabify count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @cindex tab deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 This command deletes @var{count} characters backward, changing tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 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
617 first replaced with the proper number of spaces to preserve alignment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 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
619 @var{killp} is non-@code{nil}, then the command saves the deleted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 characters in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 Conversion of tabs to spaces happens only if @var{count} is positive.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 If it is negative, exactly @minus{}@var{count} characters after point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 are deleted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 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
629 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 the kill ring.
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 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
635 @defopt backward-delete-char-untabify-method
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
636 This option specifies how @code{backward-delete-char-untabify} should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
637 deal with whitespace. Possible values include @code{untabify}, the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
638 default, meaning convert a tab to many spaces and delete one;
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
639 @code{hungry}, meaning delete all tabs and spaces before point with
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
640 one command; @code{all} meaning delete all tabs, spaces and newlines
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
641 before point, and @code{nil}, meaning do nothing special for
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
642 whitespace characters.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
643 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
644
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 @node User-Level Deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @section User-Level Deletion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 This section describes higher-level commands for deleting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
652 @deffn Command delete-horizontal-space &optional backward-only
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @cindex deleting whitespace
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 This function deletes all spaces and tabs around point. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
657 If @var{backward-only} is non-@code{nil}, the function deletes
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
658 spaces and tabs before point, but not after point.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
659
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 In the following examples, we call @code{delete-horizontal-space} four
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 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
662 characters on the line each time.
6558
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 I @point{}thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 I @point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 We@point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 Yo@point{}u thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 (delete-horizontal-space) ; @r{Four times.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 Wethought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 You thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
688 @deffn Command delete-indentation &optional join-following-p
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 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
690 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
691 space. If @var{join-following-p} is non-@code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @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
693 instead. The function returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 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
696 starts with the prefix, then @code{delete-indentation} deletes the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
697 fill prefix before joining the lines. @xref{Margins}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 In the example below, point is located on the line starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @samp{events}, and it makes no difference if there are trailing spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 in the preceding line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 @smallexample
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
704 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 When in the course of human
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
709 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 (delete-indentation)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
714 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 When in the course of human@point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
718 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @end smallexample
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 After the lines are joined, the function @code{fixup-whitespace} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 responsible for deciding whether to leave a space at the junction.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
725 @deffn Command fixup-whitespace
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
726 This function replaces all the horizontal whitespace surrounding point
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
727 with either one space or no space, according to the context. It
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
728 returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 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
731 none. Before a character with close parenthesis syntax, or after a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 character with open parenthesis or expression-prefix syntax, no space is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 Class Table}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 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
737 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
738 second invocation, point is directly after the @samp{(}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 This has too many @point{}spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 This has too many spaces at the start of (@point{} this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 This has too many spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 This has too many spaces at the start of (this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @end smallexample
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
762 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
764 @deffn Command just-one-space &optional n
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 This command replaces any spaces and tabs around point with a single
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
767 space, or @var{n} spaces if @var{n} is specified. It returns
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
768 @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @deffn Command delete-blank-lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 This function deletes blank lines surrounding point. If point is on a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 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
774 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
775 is deleted. If point is on a nonblank line, the command deletes all
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
776 blank lines immediately following it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 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
779
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @code{delete-blank-lines} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 @node The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 @section The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @cindex kill ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
787 @dfn{Kill functions} delete text like the deletion functions, but save
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 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
789 functions have @samp{kill-} in their name. By contrast, the functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 whose names start with @samp{delete-} normally do not save text for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 yanking (though they can still be undone); these are ``deletion''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 Most of the kill commands are primarily for interactive use, and are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 not described here. What we do describe are the functions provided for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 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
797 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
798 purposes within a Lisp function, you should normally use deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 functions, so as not to disturb the kill ring contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @xref{Deletion}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 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
803 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
804 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
805 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
806 @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
807 lists; there are also specialized functions, described in this section,
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
808 that treat it as a ring.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 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
811 it refers to operations that specifically @emph{do not} destroy the
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
812 entities ``killed.'' This is in sharp contrast to ordinary life, in
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 which death is permanent and ``killed'' entities do not come back to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 life. Therefore, other metaphors have been proposed. For example, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 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
816 scissors and paste to cut up and rearrange manuscripts. However, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 would be difficult to change the terminology now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 * Kill Ring Concepts:: What text looks like in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 * Kill Functions:: Functions that kill text.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
822 * Yanking:: How yanking is done.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 * Yank Commands:: Commands that access the kill ring.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
824 * Low-Level Kill Ring:: Functions and variables for kill ring access.
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
825 * Internals of Kill Ring:: Variables that hold kill ring data.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @node Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @subsection Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 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
833 first. A short kill ring, for example, might look like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 ("some text" "a different piece of text" "even older text")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 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
841 new entry automatically deletes the last entry.
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 When kill commands are interwoven with other commands, each kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 command makes a new entry in the kill ring. Multiple kill commands in
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
845 succession build up a single kill ring entry, which would be yanked as a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
846 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
847 the entry made by the first one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 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
850 the ring. Some yank commands ``rotate'' the ring by designating a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 different element as the ``front.'' But this virtual rotation doesn't
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 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
853 list.
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 @node Kill Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @subsection Functions for Killing
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 @code{kill-region} is the usual subroutine for killing text. Any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 command that calls this function is a ``kill command'' (and should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 probably have @samp{kill} in its name). @code{kill-region} puts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 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
863 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
864 @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
865 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
866
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
867 @deffn Command kill-region start end &optional yank-handler
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 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
869 @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
870 its text properties. The value is always @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 In an interactive call, @var{start} and @var{end} are point and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 the mark.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @c Emacs 19 feature
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
876 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
877 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
878 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
879 commands to copy text from a read-only buffer into the kill ring.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
880
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
881 If @var{yank-handler} is non-@code{nil}, this puts that value onto
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
882 the string of killed text, as a @code{yank-handler} text property.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
883 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
884 @code{yank-handler} properties present on the killed text are copied
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
885 onto the kill ring, like other text properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
888 @defopt kill-read-only-ok
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
889 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
890 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
891 updating the kill ring but not changing the buffer.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
892 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
893
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 @deffn Command copy-region-as-kill start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 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
896 the kill ring (including text properties), but does not delete the text
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
897 from the buffer. It returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
899 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
900 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
901
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 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
903 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
904 @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
905 Ring}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
908 @node Yanking
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
909 @subsection Yanking
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
910
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
911 Yanking means inserting text from the kill ring, but it does
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
912 not insert the text blindly. Yank commands and some other commands
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
913 use @code{insert-for-yank} to perform special processing on the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
914 text that they copy into the buffer.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
915
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
916 @defun insert-for-yank string
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
917 This function normally works like @code{insert} except that it doesn't
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
918 insert the text properties in the @code{yank-excluded-properties}
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
919 list. However, if any part of @var{string} has a non-@code{nil}
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
920 @code{yank-handler} text property, that property can do various
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
921 special processing on that part of the text being inserted.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
922 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
923
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
924 @defun insert-buffer-substring-as-yank buf &optional start end
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
925 This function resembles @code{insert-buffer-substring} except that it
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
926 doesn't insert the text properties in the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
927 @code{yank-excluded-properties} list.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
928 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
929
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
930 You can put a @code{yank-handler} text property on all or part of
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
931 the text to control how it will be inserted if it is yanked. The
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
932 @code{insert-for-yank} function looks for that property. The property
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
933 value must be a list of one to four elements, with the following
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
934 format (where elements after the first may be omitted):
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
935
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
936 @example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
937 (@var{function} @var{param} @var{noexclude} @var{undo})
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
938 @end example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
939
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
940 Here is what the elements do:
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
941
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
942 @table @var
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
943 @item function
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
944 When @var{function} is present and non-@code{nil}, it is called instead of
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
945 @code{insert} to insert the string. @var{function} takes one
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
946 argument---the string to insert.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
947
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
948 @item param
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
949 If @var{param} is present and non-@code{nil}, it replaces @var{string}
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
950 (or the part of @var{string} being processed) as the object passed to
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
951 @var{function} (or @code{insert}); for example, if @var{function} is
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
952 @code{yank-rectangle}, @var{param} should be a list of strings to
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
953 insert as a rectangle.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
954
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
955 @item noexclude
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
956 If @var{noexclude} is present and non-@code{nil}, the normal removal of the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
957 yank-excluded-properties is not performed; instead @var{function} is
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
958 responsible for removing those properties. This may be necessary
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
959 if @var{function} adjusts point before or after inserting the object.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
960
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
961 @item undo
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
962 If @var{undo} is present and non-@code{nil}, it is a function that will be
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
963 called by @code{yank-pop} to undo the insertion of the current object.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
964 It is called with two arguments, the start and end of the current
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
965 region. @var{function} can set @code{yank-undo-function} to override
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
966 the @var{undo} value.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
967 @end table
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
968
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 @node Yank Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @subsection Functions for Yanking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
973 This section describes higher-level commands for yanking, which are
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
974 intended primarily for the user but useful also in Lisp programs.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
975 Both @code{yank} and @code{yank-pop} honor the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
976 @code{yank-excluded-properties} variable and @code{yank-handler} text
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
977 property (@pxref{Yanking}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 @deffn Command yank &optional arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @cindex inserting killed text
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
981 This command inserts before point the text at the front of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 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
983 point at the end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
985 If @var{arg} is a non-@code{nil} list (which occurs interactively when
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
986 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
987 text as described above, but puts point before the yanked text and
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
988 puts the mark after it.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
989
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
990 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
991 most recently killed text---the @var{arg}th element of the kill ring
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
992 list, counted cyclically from the front, which is considered the
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
993 first element for this purpose.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
994
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
995 @code{yank} does not alter the contents of the kill ring, unless it
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
996 used text provided by another program, in which case it pushes that text
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
997 onto the kill ring. However if @var{arg} is an integer different from
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
998 one, it rotates the kill ring to place the yanked string at the front.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
999
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1000 @code{yank} returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1003 @deffn Command yank-pop &optional arg
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 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
1005 different entry from the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 This is allowed only immediately after a @code{yank} or another
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 @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
1009 inserted by yanking. @code{yank-pop} deletes that text and inserts in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 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
1011 text to the kill ring, since it is already in the kill ring somewhere.
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1012 It does however rotate the kill ring to place the newly yanked string at
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1013 the front.
6558
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 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
1016 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
1017 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
1018 kill is the replacement.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 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
1021 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
1022 oldest.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1024 The return value is always @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1027 @defvar yank-undo-function
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1028 If this variable is non-@code{nil}, the function @code{yank-pop} uses
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1029 its value instead of @code{delete-region} to delete the text
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1030 inserted by the previous @code{yank} or
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1031 @code{yank-pop} command. The value must be a function of two
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1032 arguments, the start and end of the current region.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1033
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1034 The function @code{insert-for-yank} automatically sets this variable
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1035 according to the @var{undo} element of the @code{yank-handler}
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1036 text property, if there is one.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1037 @end defvar
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1038
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1039 @node Low-Level Kill Ring
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1040 @subsection Low-Level Kill Ring
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1042 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
1043 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
1044 take care of interaction with window system selections
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1045 (@pxref{Window System Selections}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 @defun current-kill n &optional do-not-move
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1048 The function @code{current-kill} rotates the yanking pointer, which
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1049 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
1050 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
1051
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 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
1053 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
1054 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
1055
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 If @var{n} is zero, indicating a request for the latest kill,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @code{current-kill} calls the value of
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1058 @code{interprogram-paste-function} (documented below) before
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1059 consulting the kill ring. If that value is a function and calling it
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1060 returns a string, @code{current-kill} pushes that string onto the kill
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1061 ring and returns it. It also sets the yanking pointer to point to
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1062 that new entry, regardless of the value of @var{do-not-move}.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1063 Otherwise, @code{current-kill} does not treat a zero value for @var{n}
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1064 specially: it returns the entry pointed at by the yanking pointer and
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1065 does not move the yanking pointer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1068 @defun kill-new string &optional replace yank-handler
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1069 This function pushes the text @var{string} onto the kill ring and
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1070 makes the yanking pointer point to it. It discards the oldest entry
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1071 if appropriate. It also invokes the value of
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 @code{interprogram-cut-function} (see below).
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1073
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1074 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1075 first element of the kill ring with @var{string}, rather than pushing
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1076 @var{string} onto the kill ring.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1077
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1078 If @var{yank-handler} is non-@code{nil}, this puts that value onto
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1079 the string of killed text, as a @code{yank-handler} property.
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1080 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1081 @code{kill-new} copies any @code{yank-handler} properties present on
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1082 @var{string} onto the kill ring, as it does with other text properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
1085 @defun kill-append string before-p &optional yank-handler
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 This function appends the text @var{string} to the first entry in the
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1087 kill ring and makes the yanking pointer point to the combined entry.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1088 Normally @var{string} goes at the end of the entry, but if
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 @var{before-p} is non-@code{nil}, it goes at the beginning. This
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1090 function also invokes the value of @code{interprogram-cut-function}
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1091 (see below). This handles @var{yank-handler} just like
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1092 @code{kill-new}, except that if @var{yank-handler} is different from
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1093 the @code{yank-handler} property of the first entry of the kill ring,
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1094 @code{kill-append} pushes the concatenated string onto the kill ring,
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1095 instead of replacing the original first entry with it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 @defvar interprogram-paste-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 This variable provides a way of transferring killed text from other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 programs, when you are using a window system. Its value should be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @code{nil} or a function of no arguments.
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 If the value is a function, @code{current-kill} calls it to get the
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
1104 ``most recent kill.'' If the function returns a non-@code{nil} value,
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71931
diff changeset
1105 then that value is used as the ``most recent kill.'' If it returns
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1106 @code{nil}, then the front of the kill ring is used.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1108 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
1109 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
1110 another application. @xref{Window System Selections}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @defvar interprogram-cut-function
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1114 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
1115 programs, when you are using a window system. Its value should be
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1116 @code{nil} or a function of one required and one optional argument.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 If the value is a function, @code{kill-new} and @code{kill-append} call
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1119 it with the new first element of the kill ring as the first argument.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1120 The second, optional, argument has the same meaning as the @var{push}
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1121 argument to @code{x-set-cut-buffer} (@pxref{Definition of
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1122 x-set-cut-buffer}) and only affects the second and later cut buffers.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1124 The normal use of this hook is to set the window system's primary
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1125 selection (and first cut buffer) from the newly killed text.
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1126 @xref{Window System Selections}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 @node Internals of Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 @subsection Internals of the Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 The variable @code{kill-ring} holds the kill ring contents, in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 form of a list of strings. The most recent kill is always at the front
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1135 of the list.
6558
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 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
1138 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
1139 identifies the ``front'' of the ring. Moving
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @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
1141 @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
1142 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
1143 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
1144 virtual; it does not change the value of @code{kill-ring}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 variables whose values are normally lists. The word ``pointer'' in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 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
1149 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
1150 command.
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 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
1153 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
1154 @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
1155 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
1156 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
1157
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 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
1159 pointing to the second entry in the kill ring @code{("some text" "a
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1160 different piece of text" "yet older text")}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1164 kill-ring ---- kill-ring-yank-pointer
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1165 | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1166 | v
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1167 | --- --- --- --- --- ---
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1168 --> | | |------> | | |--> | | |--> nil
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1169 --- --- --- --- --- ---
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1170 | | |
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1171 | | |
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1172 | | -->"yet older text"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 | |
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1174 | --> "a different piece of text"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 --> "some text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @end example
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 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 This state of affairs might occur after @kbd{C-y} (@code{yank})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 immediately followed by @kbd{M-y} (@code{yank-pop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 @defvar kill-ring
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1185 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
1186 killed first.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 @defvar kill-ring-yank-pointer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 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
1191 ``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
1192 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
1193 that @kbd{C-y} should yank.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 @defopt kill-ring-max
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 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
1198 ring can grow, before elements are thrown away at the end. The default
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1199 value for @code{kill-ring-max} is 60.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 @node Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 @section Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 @cindex redo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1207 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
1208 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
1209 don't have one are usually special-purpose buffers for which Emacs
70626
2fe766ffb2c0 (Undo): Document that undo is turned off in buffers whose names begin with
Eli Zaretskii <eliz@gnu.org>
parents: 69903
diff changeset
1210 assumes that undoing is not useful. In particular, any buffer whose
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1211 name begins with a space has its undo recording off by default;
70626
2fe766ffb2c0 (Undo): Document that undo is turned off in buffers whose names begin with
Eli Zaretskii <eliz@gnu.org>
parents: 69903
diff changeset
1212 see @ref{Buffer Names}.) All the primitives that modify the
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1213 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
1214 list, which is in the variable @code{buffer-undo-list}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216 @defvar buffer-undo-list
65369
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65322
diff changeset
1217 This buffer-local variable's value is the undo list of the current
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65322
diff changeset
1218 buffer. A value of @code{t} disables the recording of undo information.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 Here are the kinds of elements an undo list can have:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 @table @code
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1224 @item @var{position}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1225 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
1226 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
1227 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
1228 to record where point was before the command.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @item (@var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 This kind of element indicates how to delete text that was inserted.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
1232 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
1235 @item (@var{text} . @var{position})
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 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
1237 The deleted text itself is the string @var{text}. The place to
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1238 reinsert it is @code{(abs @var{position})}. If @var{position} is
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1239 positive, point was at the beginning of the deleted text, otherwise it
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1240 was at the end.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 @item (t @var{high} . @var{low})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 This kind of element indicates that an unmodified buffer became
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 modified. The elements @var{high} and @var{low} are two integers, each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 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
1246 was previously visited or saved. @code{primitive-undo} uses those
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 values to determine whether to mark the buffer as unmodified once again;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 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
1249
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 @item (nil @var{property} @var{value} @var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 This kind of element records a change in a text property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 Here's how you might undo the change:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 (put-text-property @var{beg} @var{end} @var{property} @var{value})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1258 @item (@var{marker} . @var{adjustment})
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1259 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
1260 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
1261 @var{adjustment} character positions. Undoing this element moves
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1262 @var{marker} @minus{} @var{adjustment} characters.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
1263
60687
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1264 @item (apply @var{funname} . @var{args})
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1265 This is an extensible undo item, which is undone by calling
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1266 @var{funname} with arguments @var{args}.
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1267
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1268 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1269 This is an extensible undo item, which records a change limited to the
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1270 range @var{beg} to @var{end}, which increased the size of the buffer
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1271 by @var{delta}. It is undone by calling @var{funname} with arguments
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1272 @var{args}.
fddbd6936582 (Undo): Document extensible undo entries.
Richard M. Stallman <rms@gnu.org>
parents: 60679
diff changeset
1273
67769
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1274 This kind of element enables undo limited to a region to determine
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1275 whether the element pertains to that region.
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1276
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 This element is a boundary. The elements between two boundaries are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 called a @dfn{change group}; normally, each change group corresponds to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 one keyboard command, and undo commands normally undo an entire group as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 a unit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284 @defun undo-boundary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285 This function places a boundary element in the undo list. The undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 command stops at such a boundary, and successive undo commands undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287 to earlier and earlier boundaries. This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288
11555
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1289 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
1290 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
1291 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
1292 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
1293 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
1294 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
1295 self-inserting characters continue.
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1296
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1297 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
1298 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
1299 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
1300
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1301 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
1302 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
1303 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
1304 undo individual replacements one by one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306
58748
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1307 @defvar undo-in-progress
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1308 This variable is normally @code{nil}, but the undo commands bind it to
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1309 @code{t}. This is so that various kinds of change hooks can tell when
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1310 they're being called for the sake of undoing.
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1311 @end defvar
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1312
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 @defun primitive-undo count list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 This is the basic function for undoing elements of an undo list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 It undoes the first @var{count} elements of @var{list}, returning
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1316 the rest of @var{list}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 @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
1319 changes the buffer. Undo commands avoid confusion by saving the undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 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
1321 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
1322 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
1323 continuing to undo.
58748
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1324
e347a194391a (Undo): Document undo-in-progress.
Richard M. Stallman <rms@gnu.org>
parents: 57646
diff changeset
1325 This function does not bind @code{undo-in-progress}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328 @node Maintaining Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 @section Maintaining Undo Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 This section describes how to enable and disable undo information for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 a given buffer. It also explains how the undo list is truncated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 automatically so it doesn't get too big.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 Recording of undo information in a newly created buffer is normally
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336 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
1337 undo recording is initially disabled. You can explicitly enable or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 disable undo recording with the following two functions, or by setting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @code{buffer-undo-list} yourself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @deffn Command buffer-enable-undo &optional buffer-or-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 This command enables recording undo information for buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 @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
1344 argument is supplied, then the current buffer is used. This function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 does nothing if undo recording is already enabled in the buffer. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 In an interactive call, @var{buffer-or-name} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 You cannot specify any other buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1352 @deffn Command buffer-disable-undo &optional buffer-or-name
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1353 @cindex disabling undo
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1354 This function discards the undo list of @var{buffer-or-name}, and disables
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 further recording of undo information. As a result, it is no longer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 possible to undo either previous changes or any subsequent changes. If
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
1357 the undo list of @var{buffer-or-name} is already disabled, this function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 has no effect.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1360 This function returns @code{nil}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1361 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 As editing continues, undo lists get longer and longer. To prevent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 them from using up all available memory space, garbage collection trims
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 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
1366 of an undo list measures the cons cells that make up the list, plus the
59838
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1367 strings of deleted text.) Three variables control the range of acceptable
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1368 sizes: @code{undo-limit}, @code{undo-strong-limit} and
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1369 @code{undo-outer-limit}. In these variables, size is counted as the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1370 number of bytes occupied, which includes both saved text and other
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1371 data.
59838
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1372
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1373 @defopt undo-limit
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 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
1375 change group at which this size is exceeded is the last one kept.
59838
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1376 @end defopt
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1377
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1378 @defopt undo-strong-limit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1379 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
1380 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
1381 with all older change groups). There is one exception: the very latest
59838
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1382 change group is only discarded if it exceeds @code{undo-outer-limit}.
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1383 @end defopt
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1384
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1385 @defopt undo-outer-limit
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1386 If at garbage collection time the undo info for the current command
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
1387 exceeds this limit, Emacs discards the info and displays a warning.
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
1388 This is a last ditch limit to prevent memory overflow.
59838
5e3ad3077141 (Maintaining Undo): Add `undo-outer-limit'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59837
diff changeset
1389 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1391 @defopt undo-ask-before-discard
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1392 If this variable is non-@code{nil}, when the undo info exceeds
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1393 @code{undo-outer-limit}, Emacs asks in the echo area whether to
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1394 discard the info. The default value is @code{nil}, which means to
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1395 discard it automatically.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1396
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1397 This option is mainly intended for debugging. Garbage collection is
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1398 inhibited while the question is asked, which means that Emacs might
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1399 leak memory if the user waits too long before answering the question.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1400 @end defopt
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1401
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 @node Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 @section Filling
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1405 @cindex filling text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 @dfn{Filling} means adjusting the lengths of lines (by moving the line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 breaks) so that they are nearly (but no greater than) a specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 maximum width. Additionally, lines can be @dfn{justified}, which means
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1410 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
1411 precisely. The width is controlled by the variable @code{fill-column}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1412 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
1413
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 automatically as you insert it, but changes to existing text may leave
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 it improperly filled. Then you must fill the text explicitly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1418 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
1419 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
1420 left margin, current right margin, and current justification style
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1421 (@pxref{Margins}). If the current justification style is
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1422 @code{none}, the filling functions don't actually do anything.
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 Several of the filling functions have an argument @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1425 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
1426 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
1427 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
1428 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
1429 (see @code{current-justification}, below). Any other value is treated
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1430 as @code{full}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1431
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1432 When you call the filling functions interactively, using a prefix
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1433 argument implies the value @code{full} for @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1434
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1435 @deffn Command fill-paragraph justify
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1436 This command fills the paragraph at or after point. If
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1437 @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
1438 It uses the ordinary paragraph motion commands to find paragraph
38581
9f3e1a8c8870 Fixing some typos.
Werner LEMBERG <wl@gnu.org>
parents: 34000
diff changeset
1439 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441
25454
80ac191b6d2b *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
1442 @deffn Command fill-region start end &optional justify nosqueeze to-eop
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 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
1444 to @var{end}. It justifies as well if @var{justify} is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 non-@code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1447 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
1448 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
1449 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
1450 newline, if @code{use-hard-newlines} is enabled (see below).
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1451
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 The variable @code{paragraph-separate} controls how to distinguish
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 paragraphs. @xref{Standard Regexps}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1456 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 This command fills each paragraph in the region according to its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 individual fill prefix. Thus, if the lines of a paragraph were indented
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 with spaces, the filled paragraph will remain indented in the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 The first two arguments, @var{start} and @var{end}, are the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 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
1464 @var{justify} and @var{citation-regexp}, are optional. If
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1465 @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
1466 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
1467 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
1468 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
1469 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
1470 is treated as a citation marker.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 Ordinarily, @code{fill-individual-paragraphs} regards each change in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 indentation as starting a new paragraph. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 @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
1475 separator lines separate paragraphs. That mode can handle indented
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1476 paragraphs with additional indentation on the first line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 @defopt fill-individual-varying-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 This variable alters the action of @code{fill-individual-paragraphs} as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 described above.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1484 @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
1485 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
1486 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
1487 between paragraphs are removed. This function justifies as well as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1488 filling when @var{justify} is non-@code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1489
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1490 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
1491 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
1492 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
1493 canonicalize spaces before that position.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1494
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1495 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
1496 choose a fill prefix by default. @xref{Adaptive Fill}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1499 @deffn Command justify-current-line &optional how eop nosqueeze
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 This command inserts spaces between the words of the current line so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501 that the line ends exactly at @code{fill-column}. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 @code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1503
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1504 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
1505 of justification. It can be @code{left}, @code{right}, @code{full},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1506 @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
1507 follow specified justification style (see @code{current-justification},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1508 below). @code{nil} means to do full justification.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1509
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
1510 If @var{eop} is non-@code{nil}, that means do only left-justification
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
1511 if @code{current-justification} specifies full justification. This is
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
1512 used for the last line of a paragraph; even if the paragraph as a
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
1513 whole is fully justified, the last line should not be.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1514
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1515 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
1516 whitespace.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1519 @defopt default-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1520 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
1521 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
1522 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
1523 @code{none}. The default value is @code{left}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1524 @end defopt
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1525
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1526 @defun current-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1527 This function returns the proper justification style to use for filling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1528 the text around point.
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1529
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1530 This returns the value of the @code{justification} text property at
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1531 point, or the variable @var{default-justification} if there is no such
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1532 text property. However, it returns @code{nil} rather than @code{none}
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1533 to mean ``don't justify''.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1534 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1535
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1536 @defopt sentence-end-double-space
57402
c50e857202e2 (Filling): Add anchor for definition of `sentence-end-double-space'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 57253
diff changeset
1537 @anchor{Definition of sentence-end-double-space}
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1538 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
1539 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
1540 avoid breaking the line at such a place.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1541 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1542
60679
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1543 @defopt sentence-end-without-period
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1544 If this variable is non-@code{nil}, a sentence can end without a
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1545 period. This is used for languages like Thai, where sentences end
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1546 with a double space but without a period.
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1547 @end defopt
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1548
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1549 @defopt sentence-end-without-space
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1550 If this variable is non-@code{nil}, it should be a string of
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1551 characters that can end a sentence without following spaces.
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1552 @end defopt
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
1553
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1554 @defvar fill-paragraph-function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1555 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
1556 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
1557 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
1558 value, @code{fill-paragraph} assumes the job is done, and immediately
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1559 returns that value.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1560
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1561 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
1562 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
1563 way, it can do so as follows:
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1564
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1565 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1566 (let ((fill-paragraph-function nil))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1567 (fill-paragraph arg))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1568 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1569 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1570
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1571 @defvar use-hard-newlines
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1572 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
1573 newlines that have the @code{hard} text property. These ``hard
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1574 newlines'' act as paragraph separators.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1575 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1576
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1577 @node Margins
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1578 @section Margins for Filling
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1579
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1580 @defopt fill-prefix
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1581 This buffer-local variable, if non-@code{nil}, specifies a string of
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1582 text that appears at the beginning of normal text lines and should be
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1583 disregarded when filling them. Any line that fails to start with the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1584 fill prefix is considered the start of a paragraph; so is any line
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1585 that starts with the fill prefix followed by additional whitespace.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1586 Lines that start with the fill prefix but no additional whitespace are
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1587 ordinary text lines that can be filled together. The resulting filled
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1588 lines also start with the fill prefix.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1589
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1590 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
1591 @end defopt
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1592
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1593 @defopt fill-column
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1594 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
1595 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
1596 filling, justification, and centering commands are affected by this
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1597 variable, including Auto Fill mode (@pxref{Auto Filling}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1598
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599 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
1600 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
1601 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
1602 make the text seem clumsy.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1603 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 @defvar default-fill-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606 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
1607 buffers that do not override it. This is the same as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 @code{(default-value 'fill-column)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 The default value for @code{default-fill-column} is 70.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1613 @deffn Command set-left-margin from to margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1614 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
1615 @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
1616 command also refills the region to fit the new margin.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1617 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1618
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1619 @deffn Command set-right-margin from to margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1620 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
1621 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
1622 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
1623 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1624
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1625 @defun current-left-margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1626 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
1627 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
1628 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
1629 none), and the value of the variable @code{left-margin}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1630 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1631
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1632 @defun current-fill-column
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1633 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
1634 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
1635 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
1636 character after point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1637 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1638
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1639 @deffn Command move-to-left-margin &optional n force
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1640 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
1641 column moved to is determined by calling the function
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1642 @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
1643 @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
1644
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1645 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
1646 indentation if that doesn't match the left margin value.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1647 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1648
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1649 @defun delete-to-left-margin &optional from to
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1650 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
1651 @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
1652 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
1653 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
1654 they default to the whole buffer.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1655 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1656
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1657 @defun indent-to-left-margin
77687
d20350ec6697 (Margins): indent-to-left-margin is not the default.
Richard M. Stallman <rms@gnu.org>
parents: 77543
diff changeset
1658 This function adjusts the indentation at the beginning of the current
d20350ec6697 (Margins): indent-to-left-margin is not the default.
Richard M. Stallman <rms@gnu.org>
parents: 77543
diff changeset
1659 line to the value specified by the variable @code{left-margin}. (That
d20350ec6697 (Margins): indent-to-left-margin is not the default.
Richard M. Stallman <rms@gnu.org>
parents: 77543
diff changeset
1660 may involve either inserting or deleting whitespace.) This function
d20350ec6697 (Margins): indent-to-left-margin is not the default.
Richard M. Stallman <rms@gnu.org>
parents: 77543
diff changeset
1661 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1662 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1663
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1664 @defvar left-margin
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1665 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
1666 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
1667 becomes buffer-local when set in any fashion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1668 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1669
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1670 @defvar fill-nobreak-predicate
59945
e568af229081 (Margins): fill-nobreak-predicate can be one function.
Richard M. Stallman <rms@gnu.org>
parents: 59933
diff changeset
1671 This variable gives major modes a way to specify not to break a line
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1672 at certain places. Its value should be a list of functions. Whenever
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1673 filling considers breaking the line at a certain place in the buffer,
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1674 it calls each of these functions with no arguments and with point
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1675 located at that place. If any of the functions returns
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1676 non-@code{nil}, then the line won't be broken there.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1677 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1678
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1679 @node Adaptive Fill
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1680 @section Adaptive Fill Mode
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1681 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1682
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1683 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1684 prefix automatically from the text in each paragraph being filled
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1685 rather than using a predetermined value. During filling, this fill
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1686 prefix gets inserted at the start of the second and subsequent lines
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1687 of the paragraph as described in @ref{Filling}, and in @ref{Auto
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1688 Filling}.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1689
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1690 @defopt adaptive-fill-mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1691 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
1692 It is @code{t} by default.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1693 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1694
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1695 @defun fill-context-prefix from to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1696 This function implements the heart of Adaptive Fill mode; it chooses a
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1697 fill prefix based on the text between @var{from} and @var{to},
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1698 typically the start and end of a paragraph. It does this by looking
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1699 at the first two lines of the paragraph, based on the variables
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1700 described below.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
1701 @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
1702 @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
1703 @c in the future.
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1704
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1705 Usually, this function returns the fill prefix, a string. However,
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1706 before doing this, the function makes a final check (not specially
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1707 mentioned in the following) that a line starting with this prefix
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1708 wouldn't look like the start of a paragraph. Should this happen, the
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1709 function signals the anomaly by returning @code{nil} instead.
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1710
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1711 In detail, @code{fill-context-prefix} does this:
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1712
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1713 @enumerate
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1714 @item
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1715 It takes a candidate for the fill prefix from the first line---it
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1716 tries first the function in @code{adaptive-fill-function} (if any),
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1717 then the regular expression @code{adaptive-fill-regexp} (see below).
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1718 The first non-@code{nil} result of these, or the empty string if
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1719 they're both @code{nil}, becomes the first line's candidate.
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1720 @item
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1721 If the paragraph has as yet only one line, the function tests the
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1722 validity of the prefix candidate just found. The function then
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1723 returns the candidate if it's valid, or a string of spaces otherwise.
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1724 (see the description of @code{adaptive-fill-first-line-regexp} below).
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1725 @item
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1726 When the paragraph already has two lines, the function next looks for
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1727 a prefix candidate on the second line, in just the same way it did for
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1728 the first line. If it doesn't find one, it returns @code{nil}.
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1729 @item
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1730 The function now compares the two candidate prefixes heuristically: if
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1731 the non-whitespace characters in the line 2 candidate occur in the
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1732 same order in the line 1 candidate, the function returns the line 2
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1733 candidate. Otherwise, it returns the largest initial substring which
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1734 is common to both candidates (which might be the empty string).
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1735 @end enumerate
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1736 @end defun
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1737
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1738 @defopt adaptive-fill-regexp
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1739 Adaptive Fill mode matches this regular expression against the text
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1740 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
1741 characters it matches are that line's candidate for the fill prefix.
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1742
77061
4b4f8e1d168d (Adaptive Fill): Just describe default,
Richard M. Stallman <rms@gnu.org>
parents: 77045
diff changeset
1743 The default value matches whitespace with certain punctuation
4b4f8e1d168d (Adaptive Fill): Just describe default,
Richard M. Stallman <rms@gnu.org>
parents: 77045
diff changeset
1744 characters intermingled.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1745 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1746
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1747 @defopt adaptive-fill-first-line-regexp
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1748 Used only in one-line paragraphs, this regular expression acts as an
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1749 additional check of the validity of the one available candidate fill
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1750 prefix: the candidate must match this regular expression, or match
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1751 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1752 replaces the candidate with a string of spaces ``of the same width''
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1753 as it.
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1754
69419
e043e733d1f5 (Adaptive Fill): Fix Texinfo usage.
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
1755 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1756 matches only a string of whitespace. The effect of this default is to
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1757 force the fill prefixes found in one-line paragraphs always to be pure
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1758 whitespace.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1759 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1760
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1761 @defopt adaptive-fill-function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1762 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
1763 automatically by setting this variable to a function. The function is
63316
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1764 called with point after the left margin (if any) of a line, and it
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1765 must preserve point. It should return either ``that line's'' fill
4697645d9edc (Adaptive Fill): Amplify the description of fill-context-prefix.
Eli Zaretskii <eliz@gnu.org>
parents: 61116
diff changeset
1766 prefix or @code{nil}, meaning it has failed to determine a prefix.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1767 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1768
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 @node Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @section Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 @cindex filling, automatic
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 @cindex Auto Fill mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1775 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
1776 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
1777 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
1778 justify existing text, see @ref{Filling}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1780 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
1781 justification style to refill portions of the text. @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1782
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783 @defvar auto-fill-function
65369
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65322
diff changeset
1784 The value of this buffer-local variable should be a function (of no
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65322
diff changeset
1785 arguments) to be called after self-inserting a character from the table
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1786 @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
1787 special is done in that case.
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 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
1790 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
1791 implement the usual strategy for breaking a line.
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 @quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 In older Emacs versions, this variable was named @code{auto-fill-hook},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1795 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
1796 was renamed to @code{auto-fill-function} in version 19.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1799
16702
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1800 @defvar normal-auto-fill-function
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1801 This variable specifies the function to use for
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1802 @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
1803 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
1804 Fill works.
16702
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1805 @end defvar
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1806
28843
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1807 @defvar auto-fill-chars
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1808 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
1809 self-inserted---space and newline in most language environments. They
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1810 have an entry @code{t} in the table.
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1811 @end defvar
951c07315d97 auto-fill-chars
Dave Love <fx@gnu.org>
parents: 27654
diff changeset
1812
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1813 @node Sorting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1814 @section Sorting Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815 @cindex sorting text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1816
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1817 The sorting functions described in this section all rearrange text in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1818 a buffer. This is in contrast to the function @code{sort}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819 rearranges the order of the elements of a list (@pxref{Rearrangement}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1820 The values returned by these functions are not meaningful.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1821
67769
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1822 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1823 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
1824 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
1825 section use this function.
6558
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 To understand how @code{sort-subr} works, consider the whole accessible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828 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
1829 @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
1830 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
1831 designated as the sort key. Sorting rearranges the records in order by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 their sort keys.
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 Usually, the records are rearranged in order of ascending sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 If the first argument to the @code{sort-subr} function, @var{reverse},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 is non-@code{nil}, the sort records are rearranged in order of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 descending sort key.
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 The next four arguments to @code{sort-subr} are functions that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 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
1841 from within @code{sort-subr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 @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
1846 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
1847 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
1848 called. Therefore, you should usually move point to the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 the buffer before calling @code{sort-subr}.
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 function can indicate there are no more sort records by leaving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 point at the end of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 @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
1856 the end of the record.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1859 @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
1860 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
1861 the whole record is the sort key. If supplied, the function should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862 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
1863 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
1864 starting at point. In the latter case, @var{endkeyfun} is called to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865 find the end of the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1866
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1867 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1868 @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
1869 to the end of the sort key. This argument is optional. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1870 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1871 @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
1872 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1873 non-@code{nil} value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1874 @end enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1875
67769
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1876 The argument @var{predicate} is the function to use to compare keys.
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1877 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1878 @code{string<}.
20a39d204662 (Undo): Restore some explanation from the version that was deleted.
Richard M. Stallman <rms@gnu.org>
parents: 67763
diff changeset
1879
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1880 As an example of @code{sort-subr}, here is the complete function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1881 definition for @code{sort-lines}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1882
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1883 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1884 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885 ;; @r{Note that the first two lines of doc string}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886 ;; @r{are effectively one line when viewed by a user.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 (defun sort-lines (reverse beg end)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1888 "Sort lines in region alphabetically;\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1889 argument means descending order.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1890 Called from a program, there are three arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1892 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1893 REVERSE (non-nil means reverse order),\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1894 BEG and END (region to sort).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1895 The variable `sort-fold-case' determines\
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1896 whether alphabetic case affects
54480
8c72fab9eb5a (Sorting): Add missing quote.
Juri Linkov <juri@jurta.org>
parents: 54120
diff changeset
1897 the sort order."
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1898 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1899 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1900 (interactive "P\nr")
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1901 (save-excursion
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1902 (save-restriction
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1903 (narrow-to-region beg end)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1904 (goto-char (point-min))
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1905 (let ((inhibit-field-text-motion t))
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
1906 (sort-subr reverse 'forward-line 'end-of-line)))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1907 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1909
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1910 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
1911 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
1912 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1913 record is used as the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1914
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1915 The @code{sort-paragraphs} function is very much the same, except that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1916 its @code{sort-subr} call looks like this:
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1920 (sort-subr reverse
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1921 (function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1922 (lambda ()
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1923 (while (and (not (eobp))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1924 (looking-at paragraph-separate))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1925 (forward-line 1))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1926 'forward-paragraph)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1927 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1928 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1929
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1930 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
1931 position after @code{sort-subr} returns.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1932 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1933
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1934 @defopt sort-fold-case
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1935 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
1936 buffer sorting functions ignore case when comparing strings.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1937 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1938
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1939 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940 This command sorts the region between @var{start} and @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 If @var{reverse} is a negative integer, then sorting is in reverse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943 order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 Alphabetical sorting means that two sort keys are compared by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946 comparing the first characters of each, the second characters of each,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1947 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
1948 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
1949 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
1950 according to their numerical character codes in the Emacs character set.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 The value of the @var{record-regexp} argument specifies how to divide
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1953 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
1954 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
1955 as the next record. For example, the regular expression @samp{^.+$},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
1956 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
1957 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
1958 a description of the syntax and meaning of regular expressions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 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
1961 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
1962 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
1963 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
1964 the record moves to its new position.
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 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
1967 subexpression of @var{record-regexp}, or it can be a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 on its own.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 If @var{key-regexp} is:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 @table @asis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973 @item @samp{\@var{digit}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 grouping in @var{record-regexp} is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 @item @samp{\&}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1978 then the whole record is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1979
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 @item a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 then @code{sort-regexp-fields} searches for a match for the regular
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982 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
1983 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
1984 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
1985 changed. (The other records may move around it.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988 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
1989 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
1990 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1991 @samp{\<f\w*\>}. The resulting expression looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1992
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1993 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996 (region-beginning)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1997 (region-end))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1999 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 If you call @code{sort-regexp-fields} interactively, it prompts for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002 @var{record-regexp} and @var{key-regexp} in the minibuffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 @deffn Command sort-lines reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2006 This command alphabetically sorts lines in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 @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
2008 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2009 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2010
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2011 @deffn Command sort-paragraphs reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2012 This command alphabetically sorts paragraphs in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2013 @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
2014 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2015 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017 @deffn Command sort-pages reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018 This command alphabetically sorts pages in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 @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
2020 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2021 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2023 @deffn Command sort-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2024 This command sorts lines in the region between @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025 @var{end}, comparing them alphabetically by the @var{field}th field
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 of each line. Fields are separated by whitespace and numbered starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027 from 1. If @var{field} is negative, sorting is by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2028 @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
2029 is useful for sorting tables.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032 @deffn Command sort-numeric-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2033 This command sorts lines in the region between @var{start} and
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2034 @var{end}, comparing them numerically by the @var{field}th field of
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2035 each line. Fields are separated by whitespace and numbered starting
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2036 from 1. The specified field must contain a number in each line of the
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2037 region. Numbers starting with 0 are treated as octal, and numbers
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2038 starting with @samp{0x} are treated as hexadecimal.
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2039
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2040 If @var{field} is negative, sorting is by the
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2041 @w{@minus{}@var{field}th} field from the end of the line. This
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2042 command is useful for sorting tables.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2045 @defopt sort-numeric-base
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2046 This variable specifies the default radix for
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2047 @code{sort-numeric-fields} to parse numbers.
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2048 @end defopt
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2049
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2050 @deffn Command sort-columns reverse &optional beg end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2051 This command sorts the lines in the region between @var{beg} and
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2052 @var{end}, comparing them alphabetically by a certain range of
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2053 columns. The column positions of @var{beg} and @var{end} bound the
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
2054 range of columns to sort on.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2055
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2056 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
2057
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2058 One unusual thing about this command is that the entire line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2059 containing position @var{beg}, and the entire line containing position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060 @var{end}, are included in the region sorted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2061
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2062 Note that @code{sort-columns} rejects text that contains tabs, because
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2063 tabs could be split across the specified columns. Use @kbd{M-x
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2064 untabify} to convert tabs to spaces before sorting.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2065
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2066 When possible, this command actually works by calling the @code{sort}
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2067 utility program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070 @node Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2072 @section Counting Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 @cindex columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 @cindex counting columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 @cindex horizontal position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 The column functions convert between a character position (counting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078 characters from the beginning of the buffer) and a column position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 (counting screen characters from the beginning of a line).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2081 These functions count each character according to the number of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2082 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
2083 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
2084 @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
2085 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
2086 begins. @xref{Usual Display}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2087
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2088 Column number computations ignore the width of the window and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2089 amount of horizontal scrolling. Consequently, a column value can be
53435
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2090 arbitrarily high. The first (or leftmost) column is numbered 0. They
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2091 also ignore overlays and text properties, aside from invisibility.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2093 @defun current-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 This function returns the horizontal position of point, measured in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2095 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
2096 sum of the widths of all the displayed representations of the characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2097 between the start of the current line and point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2098
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2099 For an example of using @code{current-column}, see the description of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 @code{count-lines} in @ref{Text Lines}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 @end defun
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 @defun move-to-column column &optional force
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2104 This function moves point to @var{column} in the current line. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105 calculation of @var{column} takes into account the widths of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106 displayed representations of the characters between the start of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 line and point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2108
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2109 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
2110 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
2111 beginning of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2112
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2113 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
2114 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
2115 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
2116 @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
2117 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
2118 @var{column}. Other multicolumn characters can cause anomalies despite
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2119 @var{force}, since there is no way to split them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2120
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2121 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
2122 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
2123 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
2124
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2125 If @var{column} is not an integer, an error is signaled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2126
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2127 The return value is the column number actually moved to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2128 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2129
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2130 @node Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2131 @section Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132 @cindex indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2133
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2134 The indentation functions are used to examine, move to, and change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2135 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
2136 can also change whitespace elsewhere on a line. Columns and indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2137 count from zero at the left margin.
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 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2140 * Primitive Indent:: Functions used to count and insert indentation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2141 * Mode-Specific Indent:: Customize indentation for different modes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2142 * Region Indent:: Indent all the lines in a region.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2143 * Relative Indent:: Indent the current line based on previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2144 * Indent Tabs:: Adjustable, typewriter-like tab stops.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2145 * Motion by Indent:: Move to first non-blank character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2146 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2147
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2148 @node Primitive Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2149 @subsection Indentation Primitives
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2150
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2151 This section describes the primitive functions used to count and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2152 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
2153 primitives. @xref{Width}, for related functions.
6558
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 @defun current-indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2156 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2157 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2158 This function returns the indentation of the current line, which is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2159 the horizontal position of the first nonblank character. If the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2160 contents are entirely blank, then this is the horizontal position of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2161 end of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2162 @end defun
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 @deffn Command indent-to column &optional minimum
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2165 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2166 @comment !!SourceFile indent.c
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2167 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
2168 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
2169 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
2170 @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
2171 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
2172 indentation ends.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
2173
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
2174 The inserted whitespace characters inherit text properties from the
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
2175 surrounding text (usually, from the preceding text only). @xref{Sticky
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
2176 Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2177 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2178
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2179 @defopt indent-tabs-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2180 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2181 If this variable is non-@code{nil}, indentation functions can insert
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2182 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
2183 this variable automatically makes it buffer-local in the current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2184 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2185
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2186 @node Mode-Specific Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2187 @subsection Indentation Controlled by Major Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2188
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2189 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
2190 key to indent properly for the language being edited. This section
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2191 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
2192 The functions in this section return unpredictable values.
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 @defvar indent-line-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2195 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
2196 various commands) to indent the current line. The command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2197 @code{indent-according-to-mode} does no more than call this function.
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 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
2200 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
77687
d20350ec6697 (Margins): indent-to-left-margin is not the default.
Richard M. Stallman <rms@gnu.org>
parents: 77543
diff changeset
2201 The default value is @code{indent-relative}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2202 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2203
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2204 @deffn Command indent-according-to-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2205 This command calls the function in @code{indent-line-function} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2206 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
2207 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2208
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2209 @deffn Command indent-for-tab-command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2210 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
2211 the current line; however, if that function is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2212 @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
2213 is a trivial command that inserts a tab character.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2214 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2215
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2216 @deffn Command newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2217 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2218 This function inserts a newline, then indents the new line (the one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2219 following the newline just inserted) according to the major mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2220
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2221 It does indentation by calling the current @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2222 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2223 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2224 @code{newline-and-indent} indents to the column specified by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2225 @code{left-margin}.
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 reindent-then-newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2229 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2230 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
2231 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
2232 inserted).
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 This command does indentation on both lines according to the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2235 major mode, by calling the current value of @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2236 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2237 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238 @code{reindent-then-newline-and-indent} indents to the column specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 by @code{left-margin}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242 @node Region Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243 @subsection Indenting an Entire Region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2244
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2245 This section describes commands that indent all the lines in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 region. They return unpredictable values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2247
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2248 @deffn Command indent-region start end to-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2249 This command indents each nonblank line starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2250 (inclusive) and @var{end} (exclusive). If @var{to-column} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2251 @code{nil}, @code{indent-region} indents each nonblank line by calling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2252 the current mode's indentation function, the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2253 @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2254
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2255 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
2256 specifying the number of columns of indentation; then this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2257 gives each line exactly that much indentation, by either adding or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2258 deleting whitespace.
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 If there is a fill prefix, @code{indent-region} indents each line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2261 by making it start with the fill prefix.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262 @end deffn
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 @defvar indent-region-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2265 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
2266 @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
2267 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
2268 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
2269 region one by one, but presumably faster.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2270
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2271 If the value is @code{nil}, there is no short cut, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2272 @code{indent-region} actually works line by line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2273
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2274 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
2275 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
2276 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
2277 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
2278 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
2279 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
2280
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2281 @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
2282 a different meaning and does not use this variable.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2283 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2284
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285 @deffn Command indent-rigidly start end count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2286 @comment !!SourceFile indent.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2287 This command indents all lines starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2288 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2289 This ``preserves the shape'' of the affected region, moving it as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2290 rigid unit. Consequently, this command is useful not only for indenting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2291 regions of unindented text, but also for indenting regions of formatted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2292 code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2293
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2294 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
2295 indentation to each of the lines beginning in the region specified.
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 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
2298 @code{indent-rigidly} to indent the text copied from the message being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2299 replied to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2301
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2302 @defun indent-code-rigidly start end columns &optional nochange-regexp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2303 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
2304 that start within strings or comments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2306 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
2307 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
2308 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2309
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2310 @node Relative Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2311 @subsection Indentation Relative to Previous Lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2312
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2313 This section describes two commands that indent the current line
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2314 based on the contents of previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2315
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2316 @deffn Command indent-relative &optional unindented-ok
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2317 This command inserts whitespace at point, extending to the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2318 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
2319 indent point is a non-whitespace character following whitespace. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2320 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
2321 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
2322 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
2323 by inserting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2324
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2325 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
2326 great enough column position), @code{indent-relative} either does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2327 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2328 @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
2329 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
2330 moves point to the next tab stop by inserting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2331
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2332 The return value of @code{indent-relative} is unpredictable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2333
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2334 In the following example, point is at the beginning of the second
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2335 line:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2336
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2337 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2338 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2339 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2340 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2341 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2342 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2343
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2344 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2345 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2346 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2347
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2348 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2349 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2350 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2351 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2352 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2353 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2354
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2355 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
2356 @samp{jumped}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2357
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2358 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2359 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2360 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2361 The quick brown fox jum@point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2362 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2363 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2365 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2366 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2367 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2368
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2369 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2370 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2371 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2372 The quick brown fox jum @point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2373 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2374 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2375 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2376
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2377 @deffn Command indent-relative-maybe
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2378 @comment !!SourceFile indent.el
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2379 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
2380 by calling @code{indent-relative} with @code{t} as the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2381 @var{unindented-ok} argument. The return value is unpredictable.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2382
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383 If the previous nonblank line has no indent points beyond the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2384 column, this command does nothing.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2385 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2386
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2387 @node Indent Tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2388 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2389 @subsection Adjustable ``Tab Stops''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2390 @cindex tabs stops for indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2391
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2392 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
2393 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
2394 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
2395 typewriter. The feature works by inserting an appropriate number of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2396 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
2397 affect the display of tab characters in the buffer (@pxref{Usual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2398 Display}). Note that the @key{TAB} character as input uses this tab
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2399 stop feature only in a few major modes, such as Text mode.
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
2400 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
6558
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 @deffn Command tab-to-tab-stop
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2403 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
2404 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
2405 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
2406 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
2407 found.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2408 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2409
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2410 @defopt tab-stop-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2411 This variable is the list of tab stop columns used by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2412 @code{tab-to-tab-stops}. The elements should be integers in increasing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2413 order. The tab stop columns need not be evenly spaced.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2415 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
2416 interactively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2417 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2419 @node Motion by Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2420 @subsection Indentation-Based Motion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2421
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2422 These commands, primarily for interactive use, act based on the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2423 indentation in the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2424
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
2425 @deffn Command back-to-indentation
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2426 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2427 This command moves point to the first non-whitespace character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2428 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
2429 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2430 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2431
52544
5e831368522d (Motion by Indent): Arg to backward-to-indentation and
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2432 @deffn Command backward-to-indentation &optional arg
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2433 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2434 This command moves point backward @var{arg} lines and then to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2435 first nonblank character on that line. It returns @code{nil}.
52544
5e831368522d (Motion by Indent): Arg to backward-to-indentation and
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2436 If @var{arg} is omitted or @code{nil}, it defaults to 1.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2437 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2438
52544
5e831368522d (Motion by Indent): Arg to backward-to-indentation and
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2439 @deffn Command forward-to-indentation &optional arg
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2440 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2441 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
2442 nonblank character on that line. It returns @code{nil}.
52544
5e831368522d (Motion by Indent): Arg to backward-to-indentation and
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2443 If @var{arg} is omitted or @code{nil}, it defaults to 1.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2444 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2445
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2446 @node Case Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2447 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2448 @section Case Changes
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2449 @cindex case conversion in buffers
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2450
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2451 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
2452 buffer. @xref{Case Conversion}, for case conversion functions that work
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2453 on strings and characters. @xref{Case Tables}, for how to customize
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2454 which characters are upper or lower case and how to convert them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2455
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2456 @deffn Command capitalize-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2457 This function capitalizes all words in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2458 @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
2459 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
2460 case. The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2461
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2462 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
2463 word within the region is treated as an entire word.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2465 When @code{capitalize-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2466 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2467
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2468 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2469 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2470 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2471 This is the contents of the 5th foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2472 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2473 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2474
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2475 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2476 (capitalize-region 1 44)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2477 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2478
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2479 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2480 This Is The Contents Of The 5th Foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2481 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2482 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2483 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2484 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2485
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2486 @deffn Command downcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2487 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2488 @var{start} and @var{end} to lower case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2489 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2491 When @code{downcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2492 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2493 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2494
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2495 @deffn Command upcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2496 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2497 @var{start} and @var{end} to upper case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2498 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2499
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2500 When @code{upcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2501 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2502 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2503
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2504 @deffn Command capitalize-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2505 This function capitalizes @var{count} words after point, moving point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2506 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
2507 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
2508 If @var{count} is negative, the function capitalizes the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2509 @minus{}@var{count} previous words but does not move point. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2510 is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2511
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2512 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
2513 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
2514
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2515 When @code{capitalize-word} is called interactively, @var{count} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2516 set to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2517 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2518
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2519 @deffn Command downcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2520 This function converts the @var{count} words after point to all lower
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2521 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
2522 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2523 The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2524
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2525 When @code{downcase-word} is called interactively, @var{count} is set
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2526 to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2527 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2528
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2529 @deffn Command upcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2530 This function converts the @var{count} words after point to all upper
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2531 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
2532 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2533 The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2534
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2535 When @code{upcase-word} is called interactively, @var{count} is set to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2536 the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2537 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2539 @node Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2540 @section Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2541 @cindex text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2542 @cindex attributes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2543 @cindex properties of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2544
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2545 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
2546 property list}, much like the property list of a symbol (@pxref{Property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2547 Lists}). The properties belong to a particular character at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2548 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
2549 sentence or the first @samp{o} in @samp{foo}---if the same character
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2550 occurs in two different places, the two occurrences in general have
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2551 different properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2552
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2553 Each property has a name and a value. Both of these can be any Lisp
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2554 object, but the name is normally a symbol. Typically each property
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2555 name symbol is used for a particular purpose; for instance, the text
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2556 property @code{face} specifies the faces for displaying the character
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2557 (@pxref{Special Properties}). The usual way to access the property
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2558 list is to specify a name and ask what value corresponds to it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2559
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2560 If a character has a @code{category} property, we call it the
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2561 @dfn{property category} of the character. It should be a symbol. The
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2562 properties of the symbol serve as defaults for the properties of the
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2563 character.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2564
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2565 Copying text between strings and buffers preserves the properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2566 along with the characters; this includes such diverse functions as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2567 @code{substring}, @code{insert}, and @code{buffer-substring}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2568
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2569 @menu
40588
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2570 * Examining Properties:: Looking at the properties of one character.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2571 * 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
2572 * Property Search:: Searching for where a property changes value.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2573 * Special Properties:: Particular properties with special meanings.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2574 * Format Properties:: Properties for representing formatting of text.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2575 * Sticky Properties:: How inserted text gets properties from
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2576 neighboring text.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2577 * Saving Properties:: Saving text properties in files, and reading
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2578 them back.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2579 * Lazy Properties:: Computing text properties in a lazy fashion
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2580 only when text is examined.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2581 * 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
2582 do something when you click on them.
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
2583 * Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
40588
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2584 * Fields:: The @code{field} property defines
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2585 fields within the buffer.
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2586 * Not Intervals:: Why text properties do not use
86c8a6492402 Minor menu indentation cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 39530
diff changeset
2587 Lisp-visible text intervals.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2588 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2589
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2590 @node Examining Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2591 @subsection Examining Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2593 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
2594 a particular property of a particular character. For that, use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2595 @code{get-text-property}. Use @code{text-properties-at} to get the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2596 entire property list of a character. @xref{Property Search}, for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2597 functions to examine the properties of a number of characters at once.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2598
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2599 These functions handle both strings and buffers. Keep in mind that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2600 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
2601 from 1.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2602
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2603 @defun get-text-property pos prop &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2604 This function returns the value of the @var{prop} property of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2605 character after position @var{pos} in @var{object} (a buffer or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2606 string). The argument @var{object} is optional and defaults to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2607 current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2608
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2609 If there is no @var{prop} property strictly speaking, but the character
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2610 has a property category that is a symbol, then @code{get-text-property} returns
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2611 the @var{prop} property of that symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2612 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2613
53435
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2614 @defun get-char-property position prop &optional object
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2615 This function is like @code{get-text-property}, except that it checks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2616 overlays first and then text properties. @xref{Overlays}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2617
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2618 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
2619 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
2620 properties and overlays, but only the overlays active for that window
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2621 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
2622 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
2623 string, only text properties are considered, since strings never have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2624 overlays.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2625 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2626
53435
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2627 @defun get-char-property-and-overlay position prop &optional object
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2628 This is like @code{get-char-property}, but gives extra information
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2629 about the overlay that the property value comes from.
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2630
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2631 Its value is a cons cell whose @sc{car} is the property value, the
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2632 same value @code{get-char-property} would return with the same
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2633 arguments. Its @sc{cdr} is the overlay in which the property was
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2634 found, or @code{nil}, if it was found as a text property or not found
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2635 at all.
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2636
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2637 If @var{position} is at the end of @var{object}, both the @sc{car} and
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2638 the @sc{cdr} of the value are @code{nil}.
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2639 @end defun
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
2640
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2641 @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
2642 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
2643 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
2644 value for a property, the alternative property names are consulted in
51702
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
2645 order; the first non-@code{nil} value is used. This variable takes
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2646 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
2647 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
2648 @end defvar
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2649
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2650 @defun text-properties-at position &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2651 This function returns the entire property list of the character at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2652 @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
2653 @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2654 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2655
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2656 @defvar default-text-properties
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2657 This variable holds a property list giving default values for text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2658 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
2659 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
2660 @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
2661 used instead. Here is an example:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2662
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2663 @example
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
2664 (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
2665 char-property-alias-alist nil)
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2666 ;; @r{Make sure character 1 has no properties of its own.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2667 (set-text-properties 1 2 nil)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2668 ;; @r{What we get, when we ask, is the default value.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2669 (get-text-property 1 'foo)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2670 @result{} 69
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2671 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2672 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2673
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2674 @node Changing Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2675 @subsection Changing Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2676
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2677 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
2678 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
2679 (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
2680 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
2681 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
2682
7def48db254a Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents: 16934
diff changeset
2683 Since text properties are considered part of the contents of the
49184
55666b1c590b (Changing Properties): Say string indices are origin-0.
Richard M. Stallman <rms@gnu.org>
parents: 47475
diff changeset
2684 buffer (or string), and can affect how a buffer looks on the screen,
55666b1c590b (Changing Properties): Say string indices are origin-0.
Richard M. Stallman <rms@gnu.org>
parents: 47475
diff changeset
2685 any change in buffer text properties marks the buffer as modified.
55666b1c590b (Changing Properties): Say string indices are origin-0.
Richard M. Stallman <rms@gnu.org>
parents: 47475
diff changeset
2686 Buffer text property changes are undoable also (@pxref{Undo}).
55666b1c590b (Changing Properties): Say string indices are origin-0.
Richard M. Stallman <rms@gnu.org>
parents: 47475
diff changeset
2687 Positions in a string start from 0, whereas positions in a buffer
55666b1c590b (Changing Properties): Say string indices are origin-0.
Richard M. Stallman <rms@gnu.org>
parents: 47475
diff changeset
2688 start from 1.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2689
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2690 @defun put-text-property start end prop value &optional object
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2691 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
2692 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
2693 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
2694 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2695
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2696 @defun add-text-properties start end props &optional object
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2697 This function adds or overrides text properties for the text between
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2698 @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
2699 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2700
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2701 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
2702 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
2703 elements include the property names followed alternately by the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2704 corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2705
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2706 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2707 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
2708 its values agree with those in the text).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2709
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2710 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
2711 properties of a range of text:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2712
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2713 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2714 (add-text-properties @var{start} @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2715 '(comment t face highlight))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2716 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2717 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2718
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2719 @defun remove-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2720 This function deletes specified text properties from the text between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2721 @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
2722 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2723
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2724 The argument @var{props} specifies which properties to delete. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2725 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
2726 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2727 But only the names matter---the values that accompany them are ignored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2728 For example, here's how to remove the @code{face} property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2729
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2730 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2731 (remove-text-properties @var{start} @var{end} '(face nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2732 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2733
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2734 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2735 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
2736 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
2737
7def48db254a Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents: 16934
diff changeset
2738 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
2739 @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
2740 list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2741 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2742
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
2743 @defun remove-list-of-text-properties start end list-of-properties &optional object
60679
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
2744 Like @code{remove-text-properties} except that
68084
9b969687ff7c Fix typos.
Eli Zaretskii <eliz@gnu.org>
parents: 67930
diff changeset
2745 @var{list-of-properties} is a list of property names only, not an
60679
48eb1c71ba69 (Filling): Add sentence-end-without-period and sentence-end-without-space.
Richard M. Stallman <rms@gnu.org>
parents: 60456
diff changeset
2746 alternating list of property names and values.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
2747 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
2748
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2749 @defun set-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2750 This function completely replaces the text property list for the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2751 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
2752 If @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2754 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
2755 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2756
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2757 After @code{set-text-properties} returns, all the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2758 specified range have identical properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2759
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2760 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
2761 from the specified range of text. Here's an example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2762
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2763 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2764 (set-text-properties @var{start} @var{end} nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2765 @end example
67930
58a64605ff5a (Changing Properties): Don't use return value of set-text-properties.
Richard M. Stallman <rms@gnu.org>
parents: 67769
diff changeset
2766
58a64605ff5a (Changing Properties): Don't use return value of set-text-properties.
Richard M. Stallman <rms@gnu.org>
parents: 67769
diff changeset
2767 Do not rely on the return value of this function.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2768 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2769
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2770 The easiest way to make a string with text properties
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2771 is with @code{propertize}:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2772
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2773 @defun propertize string &rest properties
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2774 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
2775 properties @var{properties}. These properties apply to all the
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2776 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
2777 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
2778 property:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2779
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2780 @smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2781 (propertize "foo" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2782 'mouse-face 'bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2783 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2784 @end smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2785
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2786 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
2787 construct each part with @code{propertize} and then combine them with
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2788 @code{concat}:
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2789
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2790 @smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2791 (concat
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2792 (propertize "foo" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2793 'mouse-face 'bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2794 " and "
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2795 (propertize "bar" 'face 'italic
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2796 'mouse-face 'bold-italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2797 @result{} #("foo and bar"
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2798 0 3 (face italic mouse-face bold-italic)
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2799 3 8 nil
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2800 8 11 (face italic mouse-face bold-italic))
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2801 @end smallexample
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2802 @end defun
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2803
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2804 See also the function @code{buffer-substring-no-properties}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2805 (@pxref{Buffer Contents}) which copies text from the buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2806 but does not copy its properties.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2807
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2808 @node Property Search
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2809 @subsection Text Property Search Functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2810
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2811 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
2812 consecutive characters have the same value for a property. Rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2813 writing your programs to examine characters one by one, it is much
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2814 faster to process chunks of text that have the same property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2815
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2816 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
2817 comparing property values. In all cases, @var{object} defaults to the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2818 current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2819
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2820 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
2821 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
2822 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
2823 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
2824
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2825 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
2826 @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
2827 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
2828 different properties.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2829
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2830 @defun next-property-change pos &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2831 The function scans the text forward from position @var{pos} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2832 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
2833 property, then returns the position of the change. In other words, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2834 returns the position of the first character beyond @var{pos} whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2835 properties are not identical to those of the character just after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2836 @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2837
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2838 If @var{limit} is non-@code{nil}, then the scan ends at position
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
2839 @var{limit}. If there is no property change before that point,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2840 @code{next-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2841
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2842 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
2843 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
2844 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
2845 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
2846
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2847 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
2848 which all properties are constant:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2849
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2850 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2851 (while (not (eobp))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2852 (let ((plist (text-properties-at (point)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2853 (next-change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2854 (or (next-property-change (point) (current-buffer))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2855 (point-max))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2856 @r{Process text from point to @var{next-change}@dots{}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2857 (goto-char next-change)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2858 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2859 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2860
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2861 @defun previous-property-change pos &optional object limit
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2862 This is like @code{next-property-change}, but scans back from @var{pos}
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2863 instead of forward. If the value is non-@code{nil}, it is a position
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2864 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2865 equals @var{pos}.
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2866 @end defun
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2867
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2868 @defun next-single-property-change pos prop &optional object limit
71645
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2869 The function scans text for a change in the @var{prop} property, then
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2870 returns the position of the change. The scan goes forward from
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2871 position @var{pos} in the string or buffer @var{object}. In other
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2872 words, this function returns the position of the first character
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2873 beyond @var{pos} whose @var{prop} property differs from that of the
0fc55b1cc3c9 (Buffer Contents): Add example of text props in result of buffer-substring.
Richard M. Stallman <rms@gnu.org>
parents: 71374
diff changeset
2874 character just after @var{pos}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2875
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2876 If @var{limit} is non-@code{nil}, then the scan ends at position
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
2877 @var{limit}. If there is no property change before that point,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2878 @code{next-single-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2879
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2880 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
2881 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
2882 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
2883 equals @var{pos} only if @var{limit} equals @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2884 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2885
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2886 @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
2887 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
2888 @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
2889 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
2890 @var{limit} equals @var{pos}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2891 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2892
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2893 @defun next-char-property-change pos &optional limit
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2894 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
2895 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
2896 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
2897 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
2898 corresponding overlay function @code{next-overlay-change}, rather than
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2899 @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
2900 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
2901 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
2902 @end defun
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2903
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2904 @defun previous-char-property-change pos &optional limit
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2905 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
2906 @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
2907 position if no change is found.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2908 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2909
39528
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2910 @defun next-single-char-property-change pos prop &optional object limit
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2911 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
2912 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
2913 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
2914 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
2915 @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
2916 @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
2917 text-properties are considered.
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2918 @end defun
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2919
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2920 @defun previous-single-char-property-change pos prop &optional object limit
ed97ba5c9ba8 (Property Search): Correct descriptions of
Miles Bader <miles@gnu.org>
parents: 39208
diff changeset
2921 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
2922 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
2923 position in @var{object} if no change is found.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2924 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
2925
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2926 @defun text-property-any start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2927 This function returns non-@code{nil} if at least one character between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2928 @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
2929 @var{value}. More precisely, it returns the position of the first such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2930 character. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2931
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2932 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2933 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2934 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2935 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2937 @defun text-property-not-all start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2938 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
2939 @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
2940 @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
2941 character. Otherwise, it returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2942
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2943 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2944 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2945 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2946 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2947
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2948 @node Special Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2949 @subsection Properties with Special Meanings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2950
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2951 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
2952 meanings. The following sections list a few additional special property
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2953 names that control filling and property inheritance. All other names
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2954 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
2955
77839
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
2956 Note: the properties @code{composition}, @code{display},
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
2957 @code{invisible} and @code{intangible} can also cause point to move to
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
2958 an acceptable place, after each Emacs command. @xref{Adjusting
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
2959 Point}.
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
2960
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2961 @table @code
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2962 @cindex property category of text character
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2963 @kindex category @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2964 @item category
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2965 If a character has a @code{category} property, we call it the
76999
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2966 @dfn{property category} of the character. It should be a symbol. The
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2967 properties of this symbol serve as defaults for the properties of the
207f5fae3c52 Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
2968 character.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2969
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2970 @item face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2971 @cindex face codes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2972 @kindex face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2973 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
2974 text. @xref{Faces}, for more information.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2975
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2976 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
2977 then each element can be any of these possibilities;
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2978
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2979 @itemize @bullet
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2980 @item
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2981 A face name (a symbol or string).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2982
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2983 @item
59391
701be29d8965 (Special Properties): Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 58886
diff changeset
2984 A property list of face attributes. This has the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2985 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
2986 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
2987 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
2988 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
2989 @xref{Face Attributes}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2990
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2991 @item
77123
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 77121
diff changeset
2992 A cons cell with the form @code{(foreground-color . @var{color-name})} or
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2993 @code{(background-color . @var{color-name})}. These elements specify
71117
75ee8b77b134 (Special Properties): Add an xref to "Color Names".
Eli Zaretskii <eliz@gnu.org>
parents: 70626
diff changeset
2994 just the foreground color or just the background color. @xref{Color
75ee8b77b134 (Special Properties): Add an xref to "Color Names".
Eli Zaretskii <eliz@gnu.org>
parents: 70626
diff changeset
2995 Names}, for the supported forms of @var{color-name}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
2996
77123
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 77121
diff changeset
2997 A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 77121
diff changeset
2998 specifying @code{(:foreground @var{color-name})}; likewise for the
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
2999 background.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3000 @end itemize
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3001
45685
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
3002 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
3003 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
3004
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
3005 @item font-lock-face
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
3006 @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
3007 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
3008 @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
3009 @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
3010 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
3011 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
3012 @xref{Precalculated Fontification}.
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
3013
4ff98d5e3cf5 (char-property-alias-alist): New variable; describe its relation to
Colin Walters <walters@gnu.org>
parents: 45040
diff changeset
3014 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
3015 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
3016 @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
3017
59996
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59945
diff changeset
3018 This property is new in Emacs 22.1.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3019
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3020 @item mouse-face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3021 @kindex mouse-face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3022 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
3023 mouse is on or near the character. For this purpose, ``near'' means
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3024 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
3025 @code{mouse-face} property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3026
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3027 @item fontified
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3028 @kindex fontified @r{(text property)}
77846
602257788b4a (Special Properties): Correct meaning of fontified face. Text
Chong Yidong <cyd@stupidchicken.com>
parents: 77839
diff changeset
3029 This property says whether the text is ready for display. If
602257788b4a (Special Properties): Correct meaning of fontified face. Text
Chong Yidong <cyd@stupidchicken.com>
parents: 77839
diff changeset
3030 @code{nil}, Emacs's redisplay routine calls the functions in
602257788b4a (Special Properties): Correct meaning of fontified face. Text
Chong Yidong <cyd@stupidchicken.com>
parents: 77839
diff changeset
3031 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
602257788b4a (Special Properties): Correct meaning of fontified face. Text
Chong Yidong <cyd@stupidchicken.com>
parents: 77839
diff changeset
3032 part of the buffer before it is displayed. It is used internally by
602257788b4a (Special Properties): Correct meaning of fontified face. Text
Chong Yidong <cyd@stupidchicken.com>
parents: 77839
diff changeset
3033 the ``just in time'' font locking code.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3034
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3035 @item display
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3036 This property activates various features that change the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3037 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
3038 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
3039 @xref{Display Property}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3040
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3041 @item help-echo
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3042 @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
3043 @cindex tooltip
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3044 @anchor{Text help-echo}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
3045 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
3046 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
3047 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
3048 Manual}).
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3049
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
3050 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
3051 function is called with three arguments, @var{window}, @var{object} and
59770
bea71297b227 (Special Properties) <help-echo>: Use `pos' consistently in description
Eli Zaretskii <eliz@gnu.org>
parents: 59533
diff changeset
3052 @var{pos} and should return a help string or @code{nil} for
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3053 none. The first argument, @var{window} is the window in which
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3054 the help was found. The second, @var{object}, is the buffer, overlay or
59770
bea71297b227 (Special Properties) <help-echo>: Use `pos' consistently in description
Eli Zaretskii <eliz@gnu.org>
parents: 59533
diff changeset
3055 string which had the @code{help-echo} property. The @var{pos}
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3056 argument is as follows:
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3057
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3058 @itemize @bullet{}
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3059 @item
71917
c9d66abb9b2c (Special Properties): Describe fontified text property
Nick Roberts <nickrob@snap.net.nz>
parents: 71693
diff changeset
3060 If @var{object} is a buffer, @var{pos} is the position in the buffer.
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3061 @item
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3062 If @var{object} is an overlay, that overlay has a @code{help-echo}
71917
c9d66abb9b2c (Special Properties): Describe fontified text property
Nick Roberts <nickrob@snap.net.nz>
parents: 71693
diff changeset
3063 property, and @var{pos} is the position in the overlay's buffer.
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3064 @item
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3065 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
3066 with the @code{display} property), @var{pos} is the position in that
71917
c9d66abb9b2c (Special Properties): Describe fontified text property
Nick Roberts <nickrob@snap.net.nz>
parents: 71693
diff changeset
3067 string.
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3068 @end itemize
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3069
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3070 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
3071 a string, it is evaluated to obtain a help string.
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3072
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
3073 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
3074 @code{show-help-function} (@pxref{Help display}).
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3075
45750
73b33fa2ec78 Delete "new in Emacs 21" note.
Richard M. Stallman <rms@gnu.org>
parents: 45685
diff changeset
3076 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
3077
43907
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
3078 @item keymap
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
3079 @cindex keymap of character
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
3080 @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
3081 The @code{keymap} property specifies an additional keymap for
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3082 commands. When this keymap applies, it is used for key lookup before
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3083 the minor mode keymaps and before the buffer's local map.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3084 @xref{Active Keymaps}. If the property value is a symbol, the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3085 symbol's function definition is used as the keymap.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3086
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3087 The property's value for the character before point applies if it is
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3088 non-@code{nil} and rear-sticky, and the property's value for the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3089 character after point applies if it is non-@code{nil} and
53435
0f3abb6bbf27 (Examining Properties): Add get-char-property-and-overlay.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
3090 front-sticky. (For mouse clicks, the position of the click is used
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3091 instead of the position of point.)
43907
bfe50f90f666 Update doc of local-map and keymap text properties.
Richard M. Stallman <rms@gnu.org>
parents: 41490
diff changeset
3092
29102
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
3093 @item local-map
ba9cfbfc601e *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 29076
diff changeset
3094 @kindex local-map @r{(text property)}
51911
9c44faf04f59 (Special Properties): local-map and keymap properties
Richard M. Stallman <rms@gnu.org>
parents: 51702
diff changeset
3095 This property works like @code{keymap} except that it specifies a
9c44faf04f59 (Special Properties): local-map and keymap properties
Richard M. Stallman <rms@gnu.org>
parents: 51702
diff changeset
3096 keymap to use @emph{instead of} the buffer's local map. For most
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3097 purposes (perhaps all purposes), it is better to use the @code{keymap}
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3098 property.
34000
bbedc7c6ec6f keymap property
Dave Love <fx@gnu.org>
parents: 33911
diff changeset
3099
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3100 @item syntax-table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3101 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
3102 about this particular character. @xref{Syntax Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3103
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3104 @item read-only
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3105 @cindex read-only character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3106 @kindex read-only @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3107 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
3108 character is not allowed. Any command that would do so gets an error,
71374
a358bd87a242 (Special Properties): String value of `read-only' serves as the error message.
Richard M. Stallman <rms@gnu.org>
parents: 71117
diff changeset
3109 @code{text-read-only}. If the property value is a string, that string
a358bd87a242 (Special Properties): String value of `read-only' serves as the error message.
Richard M. Stallman <rms@gnu.org>
parents: 71117
diff changeset
3110 is used as the error message.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3111
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3112 Insertion next to a read-only character is an error if inserting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3113 ordinary text there would inherit the @code{read-only} property due to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3114 stickiness. Thus, you can control permission to insert next to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3115 read-only text by controlling the stickiness. @xref{Sticky Properties}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3116
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3117 Since changing properties counts as modifying the buffer, it is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3118 possible to remove a @code{read-only} property unless you know the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3119 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
3120 and then remove the property. @xref{Read Only Buffers}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3122 @item invisible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3123 @kindex invisible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3124 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
3125 on the screen. @xref{Invisible Text}, for details.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3126
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3127 @item intangible
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3128 @kindex intangible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3129 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
3130 @code{intangible} properties, then you cannot place point between them.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3131 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
3132 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
3133 point actually moves to the start of the group.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3134
77839
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
3135 If consecutive characters have unequal non-@code{nil}
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
3136 @code{intangible} properties, they belong to separate groups; each
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
3137 group is separately treated as described above.
3ca4fe7ebcb6 (Special Properties): Add link to Adjusting Point.
Richard M. Stallman <rms@gnu.org>
parents: 77687
diff changeset
3138
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3139 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
3140 the @code{intangible} property is ignored.
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
3141
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3142 @item field
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3143 @kindex field @r{(text property)}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3144 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
3145 @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
3146 @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
3147 @xref{Fields}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3148
57192
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3149 @item cursor
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3150 @kindex cursor @r{(text property)}
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3151 Normally, the cursor is displayed at the end of any overlay and text
57222
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3152 property strings present at the current window position. You can
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3153 place the cursor on any desired character of these strings by giving
57192
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3154 that character a non-@code{nil} @var{cursor} text property.
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3155
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3156 @item pointer
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3157 @kindex pointer @r{(text property)}
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3158 This specifies a specific pointer shape when the mouse pointer is over
63353
138377d5ea9f (Special Properties): Fix cross reference.
Lute Kamstra <lute@gnu.org>
parents: 63316
diff changeset
3159 this text or image. @xref{Pointer Shape}, for possible pointer
138377d5ea9f (Special Properties): Fix cross reference.
Lute Kamstra <lute@gnu.org>
parents: 63316
diff changeset
3160 shapes.
57192
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3161
57222
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3162 @item line-spacing
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3163 @kindex line-spacing @r{(text property)}
57253
1aa63962c3cf (Special Properties): Clarify line-spacing and line-height.
Richard M. Stallman <rms@gnu.org>
parents: 57222
diff changeset
3164 A newline can have a @code{line-spacing} text or overlay property that
1aa63962c3cf (Special Properties): Clarify line-spacing and line-height.
Richard M. Stallman <rms@gnu.org>
parents: 57222
diff changeset
3165 controls the height of the display line ending with that newline. The
1aa63962c3cf (Special Properties): Clarify line-spacing and line-height.
Richard M. Stallman <rms@gnu.org>
parents: 57222
diff changeset
3166 property value overrides the default frame line spacing and the buffer
58886
bf57a566c090 * text.texi (Special Properties): Just mention line-spacing and
Kim F. Storm <storm@cua.dk>
parents: 58748
diff changeset
3167 local @code{line-spacing} variable. @xref{Line Height}.
57222
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3168
57192
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3169 @item line-height
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3170 @kindex line-height @r{(text property)}
57222
f0af4b0029b5 (Special Properties): Cleanups in `cursor'.
Richard M. Stallman <rms@gnu.org>
parents: 57192
diff changeset
3171 A newline can have a @code{line-height} text or overlay property that
57253
1aa63962c3cf (Special Properties): Clarify line-spacing and line-height.
Richard M. Stallman <rms@gnu.org>
parents: 57222
diff changeset
3172 controls the total height of the display line ending in that newline.
58886
bf57a566c090 * text.texi (Special Properties): Just mention line-spacing and
Kim F. Storm <storm@cua.dk>
parents: 58748
diff changeset
3173 @xref{Line Height}.
57192
ba03d6f29083 (Special Properties): Add `cursor', `pointer',
Kim F. Storm <storm@cua.dk>
parents: 54916
diff changeset
3174
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3175 @item modification-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3176 @cindex change hooks for a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3177 @cindex hooks for changing a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3178 @kindex modification-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3179 If a character has the property @code{modification-hooks}, then its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3180 value should be a list of functions; modifying that character calls all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3181 of those functions. Each function receives two arguments: the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3182 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
3183 particular modification hook function appears on several characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3184 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
3185 the function will be called.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3186
63950
a56fccc4986b (Special Properties): Change hook functions should bind
Richard M. Stallman <rms@gnu.org>
parents: 63609
diff changeset
3187 If these functions modify the buffer, they should bind
a56fccc4986b (Special Properties): Change hook functions should bind
Richard M. Stallman <rms@gnu.org>
parents: 63609
diff changeset
3188 @code{inhibit-modification-hooks} to @code{t} around doing so, to
a56fccc4986b (Special Properties): Change hook functions should bind
Richard M. Stallman <rms@gnu.org>
parents: 63609
diff changeset
3189 avoid confusing the internal mechanism that calls these hooks.
a56fccc4986b (Special Properties): Change hook functions should bind
Richard M. Stallman <rms@gnu.org>
parents: 63609
diff changeset
3190
77543
3c9f4556ffca (Special Properties): Add xref to Overlay Properties.
Richard M. Stallman <rms@gnu.org>
parents: 77362
diff changeset
3191 Overlays also support the @code{modification-hooks} property, but the
3c9f4556ffca (Special Properties): Add xref to Overlay Properties.
Richard M. Stallman <rms@gnu.org>
parents: 77362
diff changeset
3192 details are somewhat different (@pxref{Overlay Properties}).
3c9f4556ffca (Special Properties): Add xref to Overlay Properties.
Richard M. Stallman <rms@gnu.org>
parents: 77362
diff changeset
3193
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3194 @item insert-in-front-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3195 @itemx insert-behind-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3196 @kindex insert-in-front-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3197 @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
3198 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
3199 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
3200 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
3201 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
3202 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
3203 @emph{after} the actual insertion takes place.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3205 See also @ref{Change Hooks}, for other hooks that are called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3206 when you change text in a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3207
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3208 @item point-entered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3209 @itemx point-left
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3210 @cindex hooks for motion of point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3211 @kindex point-entered @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3212 @kindex point-left @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3213 The special properties @code{point-entered} and @code{point-left}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3214 record hook functions that report motion of point. Each time point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3215 moves, Emacs compares these two property values:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3216
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3217 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3218 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3219 the @code{point-left} property of the character after the old location,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3220 and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3221 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3222 the @code{point-entered} property of the character after the new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3223 location.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3224 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3226 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3227 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
3228 with two arguments: the old value of point, and the new one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3229
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3230 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
3231 locations. The result may be to execute two @code{point-left} functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3232 (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
3233 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
3234 @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
3235 @code{point-entered} functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3236
54041
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
3237 It is possible with @code{char-after} to examine characters at various
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
3238 buffer positions without moving point to those positions. Only an
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53435
diff changeset
3239 actual change in the value of point runs these hook functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3240
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3241 @defvar inhibit-point-motion-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3242 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
3243 @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
3244 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
3245 @code{let}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3246 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3247
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3248 @defvar show-help-function
31372
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
3249 @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
3250 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
3251 properties, menu help strings (@pxref{Simple Menu Items},
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
3252 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3004c92de7b0 help-echo stuff
Dave Love <fx@gnu.org>
parents: 31079
diff changeset
3253 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
3254 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
9f3e1a8c8870 Fixing some typos.
Werner LEMBERG <wl@gnu.org>
parents: 34000
diff changeset
3255 Manual}) provides an example.
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3256 @end defvar
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
3257
77303
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3258 @item composition
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3259 @kindex composition @r{(text property)}
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3260 This text property is used to display a sequence of characters as a
77362
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3261 single glyph composed from components. For instance, in Thai a base
77303
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3262 consonant is composed with the following combining vowel as a single
77362
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3263 glyph. The value should be a character or a sequence (vector, list,
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3264 or string) of integers.
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3265
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3266 @itemize @bullet
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3267 @item
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3268 If it is a character, it means to display that character instead of
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3269 the text in the region.
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3270
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3271 @item
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3272 If it is a string, it means to display that string's contents instead
77303
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3273 of the text in the region.
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3274
77362
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3275 @item
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3276 If it is a vector or list, the elements are characters interleaved
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3277 with internal codes specifying how to compose the following character
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3278 with the previous one.
bcccf7e23d1c (Special Properties): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77303
diff changeset
3279 @end itemize
77303
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3280 @end table
f988436b1743 (Special Properties): Document composition property.
Kenichi Handa <handa@m17n.org>
parents: 77123
diff changeset
3281
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3282 @node Format Properties
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3283 @subsection Formatted Text Properties
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3284
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3285 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
3286 are used for representing formatted text. @xref{Filling}, and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3287 @ref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3288
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3289 @table @code
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3290 @item hard
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3291 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
3292 The fill commands do not alter hard newlines and do not move words
59880
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
3293 across them. However, this property takes effect only if the
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
3294 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
8e65810e7f24 (User-Level Deletion): just-one-space takes numeric arg.
Richard M. Stallman <rms@gnu.org>
parents: 59838
diff changeset
3295 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3296
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3297 @item right-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3298 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
3299 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3300
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3301 @item left-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3302 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
3303 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3304
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3305 @item justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3306 This property specifies the style of justification for filling this part
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3307 of the text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3308 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
3309
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3310 @node Sticky Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3311 @subsection Stickiness of Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3312 @cindex sticky text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3313 @cindex inheritance of text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3314
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3315 Self-inserting characters normally take on the same properties as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3316 preceding character. This is called @dfn{inheritance} of properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3317
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3318 In a Lisp program, you can do insertion with inheritance or without,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3319 depending on your choice of insertion primitive. The ordinary text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3320 insertion functions such as @code{insert} do not inherit any properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3321 They insert text with precisely the properties of the string being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3322 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
3323 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
3324 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
3325 section. Self-inserting characters inherit properties because they work
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
3326 using these primitives.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3327
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3328 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
3329 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
3330 Insertion after a character inherits those of its properties that are
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3331 @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
3332 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
3333 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
3334 takes precedence.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3335
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3336 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
3337 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
3338 and nothing from the following character.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3339
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3340 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
3341 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
3342 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
3343 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
3344 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
3345 sticky or nonsticky in any particular part of the text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3346
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3347 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
3348 its properties are front-sticky. If the @code{front-sticky} property is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3349 a list, then the sticky properties of the character are those whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3350 names are in the list. For example, if a character has a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3351 @code{front-sticky} property whose value is @code{(face read-only)},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3352 then insertion before the character can inherit its @code{face} property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3353 and its @code{read-only} property, but no others.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3354
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3355 The @code{rear-nonsticky} property works the opposite way. Most
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3356 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
3357 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
3358 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
3359 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
3360 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
3361 list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3362
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3363 @defvar text-property-default-nonsticky
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3364 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
3365 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
3366 @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
3367 stickiness of a particular text property, @var{property}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3368
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3369 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
3370 @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
3371 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
3372 directions by default.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3373
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3374 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
3375 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
3376 @code{text-property-default-nonsticky}.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3377 @end defvar
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3378
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3379 Here are the functions that insert text with inheritance of properties:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3380
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3381 @defun insert-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3382 Insert the strings @var{strings}, just like the function @code{insert},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3383 but inherit any sticky properties from the adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3384 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3385
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3386 @defun insert-before-markers-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3387 Insert the strings @var{strings}, just like the function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3388 @code{insert-before-markers}, but inherit any sticky properties from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3389 adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3390 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3391
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3392 @xref{Insertion}, for the ordinary insertion functions which do not
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3393 inherit.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3394
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3395 @node Saving Properties
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
3396 @subsection Saving Text Properties in Files
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3397 @cindex text properties in files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3398 @cindex saving text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3399
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3400 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
3401 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
3402 files, using these two hooks:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3403
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3404 @defvar write-region-annotate-functions
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3405 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
3406 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
3407 being written in the file. @xref{Writing to Files}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3408
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3409 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
3410 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
3411 contents of the buffer. Instead, they should return lists indicating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3412 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
3413 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3415 Each function should return a list of elements of the form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3416 @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
3417 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
3418 and @var{string} is the annotation to add there.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3419
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3420 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
3421 increasing order by @var{position}. If there is more than one function,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3422 @code{write-region} merges the lists destructively into one sorted list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3424 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
3425 file, it intermixes the specified annotations at the corresponding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3426 positions. All this takes place without modifying the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3427 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3428
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3429 @defvar after-insert-file-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3430 This variable holds a list of functions for @code{insert-file-contents}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3431 to call after inserting a file's contents. These functions should scan
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3432 the inserted text for annotations, and convert them to the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3433 properties they stand for.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3434
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3435 Each function receives one argument, the length of the inserted text;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3436 point indicates the start of that text. The function should scan that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3437 text for annotations, delete them, and create the text properties that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3438 the annotations specify. The function should return the updated length
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3439 of the inserted text, as it stands after those changes. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3440 returned by one function becomes the argument to the next function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3441
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3442 These functions should always return with point at the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3443 the inserted text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3444
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3445 The intended use of @code{after-insert-file-functions} is for converting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3446 some sort of textual annotations into actual text properties. But other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3447 uses may be possible.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3448 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3449
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3450 We invite users to write Lisp programs to store and retrieve text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3451 properties in files, using these hooks, and thus to experiment with
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49184
diff changeset
3452 various data formats and find good ones. Eventually we hope users
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3453 will produce good, general extensions we can install in Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3454
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3455 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
3456 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
3457 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
3458 are reasonably flexible, and not too hard to encode.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3459
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3460 @xref{Format Conversion}, for a related feature.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3461
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3462 @c ??? In next edition, merge this info Format Conversion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3463
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3464 @node Lazy Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3465 @subsection Lazy Computation of Text Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3466
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3467 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
3468 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
3469 when and if something depends on them.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3470
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3471 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
3472 properties is @code{buffer-substring}. Before examining the properties,
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3473 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
3474
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3475 @defvar buffer-access-fontify-functions
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3476 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
3477 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
3478 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
3479 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
3480 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
3481 buffer.)
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3482 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3483
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3484 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
3485 functions, since it ignores text properties anyway.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3486
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3487 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
3488 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
3489 @code{buffer-access-fontified-property}.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3490
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3491 @defvar buffer-access-fontified-property
77121
3757055699dd (Lazy Properties): Minor fix.
Richard M. Stallman <rms@gnu.org>
parents: 77061
diff changeset
3492 If this variable's value is non-@code{nil}, it is a symbol which is used
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3493 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
3494 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
3495 computed.''
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3496
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3497 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
3498 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
3499 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
3500 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
3501 just copies the properties they already have.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3502
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3503 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
3504 @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
3505 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
3506 being called over and over for the same text.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3507 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
3508
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3509 @node Clickable Text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3510 @subsection Defining Clickable Text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3511 @cindex clickable text
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3512
72381
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3513 @dfn{Clickable text} is text that can be clicked, with either the
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3514 the mouse or via keyboard commands, to produce some result. Many
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3515 major modes use clickable text to implement features such as
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3516 hyper-links. The @code{button} package provides an easy way to insert
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3517 and manipulate clickable text. @xref{Buttons}.
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3518
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3519 In this section, we will explain how to manually set up clickable
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3520 text in a buffer using text properties. This involves two things: (1)
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3521 indicating clickability when the mouse moves over the text, and (2)
4300054c252b * text.texi (Near Point): Say "cursor" not "terminal cursor".
Chong Yidong <cyd@stupidchicken.com>
parents: 72216
diff changeset
3522 making @kbd{RET} or a mouse click on that text do something.
72110
d64250333611 (Clickable Text): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 72078
diff changeset
3523
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3524 Indicating clickability usually involves highlighting the text, and
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3525 often involves displaying helpful information about the action, such
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3526 as which mouse button to press, or a short summary of the action.
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3527 This can be done with the @code{mouse-face} and @code{help-echo}
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3528 text properties. @xref{Special Properties}.
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3529 Here is an example of how Dired does it:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3530
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3531 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3532 (condition-case nil
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3533 (if (dired-move-to-filename)
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3534 (add-text-properties
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3535 (point)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3536 (save-excursion
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3537 (dired-move-to-end-of-filename)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3538 (point))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3539 '(mouse-face highlight
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3540 help-echo "mouse-2: visit this file in other window")))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3541 (error nil))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3542 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3543
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3544 @noindent
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3545 The first two arguments to @code{add-text-properties} specify the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3546 beginning and end of the text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3547
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3548 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
3549 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
3550 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
3551 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
3552
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3553 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3554 (defun dired-mouse-find-file-other-window (event)
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3555 "In Dired, visit the file or directory name you click on."
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3556 (interactive "e")
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3557 (let (window pos file)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3558 (save-excursion
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3559 (setq window (posn-window (event-end event))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3560 pos (posn-point (event-end event)))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3561 (if (not (windowp window))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3562 (error "No file chosen"))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3563 (set-buffer (window-buffer window))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3564 (goto-char pos)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3565 (setq file (dired-get-file-for-visit)))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3566 (if (file-directory-p file)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3567 (or (and (cdr dired-subdir-alist)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3568 (dired-goto-subdir file))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3569 (progn
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3570 (select-window window)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3571 (dired-other-window file)))
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3572 (select-window window)
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3573 (find-file-other-window (file-name-sans-versions file t)))))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3574 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3575
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3576 @noindent
72216
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3577 The reason for the @code{save-excursion} construct is to avoid
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3578 changing the current buffer. In this case,
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3579 Dired uses the functions @code{posn-window} and @code{posn-point}
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3580 to determine which buffer the click happened in and where, and
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3581 in that buffer, @code{dired-get-file-for-visit} to determine which
6b63f7efd5b6 (Clickable Text): Mention `help-echo' text property.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72193
diff changeset
3582 file to visit.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3583
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3584 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
3585 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
3586 text property:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3587
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3588 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3589 (let ((map (make-sparse-keymap)))
31586
b51dba45cbe7 (Clickable Text): Fix example.
Dave Love <fx@gnu.org>
parents: 31372
diff changeset
3590 (define-key map [mouse-2] 'operate-this-button)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3591 (put-text-property (point)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3592 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3593 (dired-move-to-end-of-filename)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3594 (point))
31586
b51dba45cbe7 (Clickable Text): Fix example.
Dave Love <fx@gnu.org>
parents: 31372
diff changeset
3595 'keymap map))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3596 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3597
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3598 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3599 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
3600 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
3601 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
3602 buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3603
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3604 @node Links and Mouse-1
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3605 @subsection Links and Mouse-1
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3606 @cindex follow links
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3607 @cindex mouse-1
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3608
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3609 The normal Emacs command for activating text in read-only buffers is
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3610 @key{Mouse-2}, which includes following textual links. However, most
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3611 graphical applications use @key{Mouse-1} for following links. For
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3612 compatibility, @key{Mouse-1} follows links in Emacs too, when you
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3613 click on a link quickly without moving the mouse. The user can
63609
99ab8bedbc9d Fix spellings.
Juanma Barranquero <lekktu@gmail.com>
parents: 63583
diff changeset
3614 customize this behavior through the variable
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3615 @code{mouse-1-click-follows-link}.
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3616
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3617 To define text as a link at the Lisp level, you should bind the
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3618 @code{mouse-2} event to a command to follow the link. Then, to indicate that
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3619 @key{Mouse-1} should also follow the link, you should specify a
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3620 @code{follow-link} condition either as a text property or as a key
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3621 binding:
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3622
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3623 @table @asis
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3624 @item @code{follow-link} property
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3625 If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3626 property, that specifies the condition.
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3627
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3628 @item @code{follow-link} event
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3629 If there is a binding for the @code{follow-link} event, either on the
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3630 clickable text or in the local keymap, the binding is the condition.
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3631 @end table
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3632
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3633 Regardless of how you set the @code{follow-link} condition, its
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3634 value is used as follows to determine whether the given position is
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3635 inside a link, and (if so) to compute an @dfn{action code} saying how
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3636 @key{Mouse-1} should handle the link.
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3637
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3638 @table @asis
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3639 @item @code{mouse-face}
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3640 If the condition is @code{mouse-face}, a position is inside a link if
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3641 there is a non-@code{nil} @code{mouse-face} property at that position.
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3642 The action code is always @code{t}.
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3643
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3644 For example, here is how Info mode handles @key{Mouse-1}:
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3645
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
3646 @smallexample
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3647 (define-key Info-mode-map [follow-link] 'mouse-face)
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
3648 @end smallexample
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3649
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3650 @item a function
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3651 If the condition is a valid function, @var{func}, then a position
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3652 @var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3653 to non-@code{nil}. The value returned by @var{func} serves as the
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3654 action code.
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3655
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3656 For example, here is how pcvs enables @key{Mouse-1} to follow links on
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3657 file names only:
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3658
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
3659 @smallexample
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3660 (define-key map [follow-link]
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3661 (lambda (pos)
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
3662 (eq (get-char-property pos 'face) 'cvs-filename-face)))
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63353
diff changeset
3663 @end smallexample
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3664
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3665 @item anything else
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3666 If the condition value is anything else, then the position is inside a
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3667 link and the condition itself is the action code. Clearly you should
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3668 only specify this kind of condition on the text that constitutes a
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3669 link.
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3670 @end table
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3671
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3672 @noindent
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3673 The action code tells @key{Mouse-1} how to follow the link:
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3674
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3675 @table @asis
59533
2a346f1b2a9f (Links and Mouse-1): Fix string and vector item.
Kim F. Storm <storm@cua.dk>
parents: 59524
diff changeset
3676 @item a string or vector
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3677 If the action code is a string or vector, the @key{Mouse-1} event is
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3678 translated into the first element of the string or vector; i.e., the
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3679 action of the @key{Mouse-1} click is the local or global binding of
59533
2a346f1b2a9f (Links and Mouse-1): Fix string and vector item.
Kim F. Storm <storm@cua.dk>
parents: 59524
diff changeset
3680 that character or symbol. Thus, if the action code is @code{"foo"},
59524
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3681 @key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
8f17a7431c8a (Links and Mouse-1): Clarify text.
Richard M. Stallman <rms@gnu.org>
parents: 59504
diff changeset
3682 @key{Mouse-1} translates into @key{foo}.
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3683
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3684 @item anything else
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3685 For any other non-@code{nil} action code, the @code{mouse-1} event is
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3686 translated into a @code{mouse-2} event at the same position.
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3687 @end table
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3688
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3689 To define @key{Mouse-1} to activate a button defined with
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3690 @code{define-button-type}, give the button a @code{follow-link}
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3691 property with a value as specified above to determine how to follow
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3692 the link. For example, here is how Help mode handles @key{Mouse-1}:
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3693
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3694 @smallexample
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3695 (define-button-type 'help-xref
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3696 'follow-link t
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3697 'action #'help-button-action)
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3698 @end smallexample
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3699
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3700 To define @key{Mouse-1} on a widget defined with
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3701 @code{define-widget}, give the widget a @code{:follow-link} property
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3702 with a value as specified above to determine how to follow the link.
59504
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3703
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3704 For example, here is how the @code{link} widget specifies that
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3705 a @key{Mouse-1} click shall be translated to @key{RET}:
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3706
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3707 @smallexample
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3708 (define-widget 'link 'item
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3709 "An embedded link."
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3710 :button-prefix 'widget-link-prefix
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3711 :button-suffix 'widget-link-suffix
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3712 :follow-link "\C-m"
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3713 :help-echo "Follow the link."
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3714 :format "%[%t%]")
66f927c186ac (Links and Mouse-1): Rename section from Enabling
Kim F. Storm <storm@cua.dk>
parents: 59494
diff changeset
3715 @end smallexample
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3716
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3717 @defun mouse-on-link-p pos
59494
d8cf3d034936 (Enabling Mouse-1 to Follow Links): Rewrite.
Richard M. Stallman <rms@gnu.org>
parents: 59464
diff changeset
3718 This function returns non-@code{nil} if position @var{pos} in the
72078
5d973bcbba35 (Links and Mouse-1): For mouse-on-link-p, expand on arg POS.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 71956
diff changeset
3719 current buffer is on a link. @var{pos} can also be a mouse event
5d973bcbba35 (Links and Mouse-1): For mouse-on-link-p, expand on arg POS.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 71956
diff changeset
3720 location, as returned by @code{event-start} (@pxref{Accessing Events}).
59464
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3721 @end defun
07659a11876d (Text Properties): Add "Enable Mouse-1" to submenu.
Kim F. Storm <storm@cua.dk>
parents: 59391
diff changeset
3722
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3723 @node Fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3724 @subsection Defining and Using Fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3725 @cindex fields
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3726
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3727 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
3728 identified by having the same value (comparing with @code{eq}) of the
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3729 @code{field} property (either a text-property or an overlay property).
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3730 This section describes special functions that are available for
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3731 operating on fields.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3732
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3733 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
3734 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
3735 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
3736
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3737 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
3738 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
3739 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
3740 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
3741 @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
3742 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
3743 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
3744
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3745 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
3746 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
3747 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
3748 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
3749 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
3750 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
3751 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
3752
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3753 In all of these functions, if @var{pos} is omitted or @code{nil}, the
72193
bbb689ae03ca (Fields): Mention POS requirement when narrowing is in effect.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72110
diff changeset
3754 value of point is used by default. If narrowing is in effect, then
bbb689ae03ca (Fields): Mention POS requirement when narrowing is in effect.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 72110
diff changeset
3755 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3756
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3757 @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
3758 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
3759
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3760 If @var{pos} is at the beginning of its field, and
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3761 @var{escape-from-edge} is non-@code{nil}, then the return value is
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3762 always the beginning of the preceding field that @emph{ends} at @var{pos},
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3763 regardless of the stickiness of the @code{field} properties around
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3764 @var{pos}.
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3765
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3766 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
3767 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
3768 returned instead.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3769 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3770
41490
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3771 @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
3772 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
3773
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3774 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
3775 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
3776 field that @emph{begins} at @var{pos}, regardless of the stickiness of
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3777 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
3778
794e4afabce0 (Fields): Describe new `limit' arg in field-beginning/field-end.
Miles Bader <miles@gnu.org>
parents: 40588
diff changeset
3779 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
3780 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
3781 instead.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3782 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3783
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3784 @defun field-string &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3785 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
3786 as a string.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3787 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3788
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3789 @defun field-string-no-properties &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3790 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
3791 as a string, discarding text properties.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3792 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3793
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3794 @defun delete-field &optional pos
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3795 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
3796 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3797
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3798 @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
3799 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
3800 @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
3801 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
3802
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3803 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
72975
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3804 the value of point instead, and moves point to the resulting position
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3805 as well as returning it.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3806
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3807 If @var{old-pos} is at the boundary of two fields, then the acceptable
72975
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3808 final positions depend on the argument @var{escape-from-edge}. If
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3809 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3810 the field whose @code{field} property equals what new characters
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3811 inserted at @var{old-pos} would inherit. (This depends on the
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3812 stickiness of the @code{field} property for the characters before and
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3813 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
72975
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3814 @var{new-pos} can be anywhere in the two adjacent fields.
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3815 Additionally, if two fields are separated by another field with the
72975
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3816 special value @code{boundary}, then any point within this special
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3817 field is also considered to be ``on the boundary.''
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3818
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3819 Commands like @kbd{C-a} with no argumemt, that normally move backward
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3820 to a specific kind of location and stay there once there, probably
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3821 should specify @code{nil} for @var{escape-from-edge}. Other motion
77837c7f1fa0 (Fields): Clarify explanation of constrain-to-field.
Richard M. Stallman <rms@gnu.org>
parents: 72381
diff changeset
3822 commands that check fields should probably pass @code{t}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3823
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3824 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
3825 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
3826 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
3827 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
3828 @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
3829 the case where they can still move to the right line.
32091
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3830
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3831 If the optional argument @var{inhibit-capture-property} is
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3832 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
3833 name, then any field boundaries are ignored.
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3834
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3835 You can cause @code{constrain-to-field} to ignore all field boundaries
0c00f9d38595 (Fields):
Miles Bader <miles@gnu.org>
parents: 31586
diff changeset
3836 (and so never constrain anything) by binding the variable
51702
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
3837 @code{inhibit-field-text-motion} to a non-@code{nil} value.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3838 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25875
diff changeset
3839
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3840 @node Not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3841 @subsection Why Text Properties are not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3842 @cindex intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3843
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3844 Some editors that support adding attributes to text in the buffer do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3845 so by letting the user specify ``intervals'' within the text, and adding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3846 the properties to the intervals. Those editors permit the user or the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3847 programmer to determine where individual intervals start and end. We
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3848 deliberately provided a different sort of interface in Emacs Lisp to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3849 avoid certain paradoxical behavior associated with text modification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3850
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3851 If the actual subdivision into intervals is meaningful, that means you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3852 can distinguish between a buffer that is just one interval with a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3853 certain property, and a buffer containing the same text subdivided into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3854 two intervals, both of which have that property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3855
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3856 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
3857 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
3858 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
3859 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
3860 same properties. Thus, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3861 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3862
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3863 Suppose we ``fix'' this problem by coalescing the two intervals when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3864 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
3865 single interval. But suppose instead that we have two adjacent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3866 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
3867 and yank it back. The same interval-coalescence feature that rescues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3868 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
3869 one interval. One again, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3870 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3871
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3872 Insertion of text at the border between intervals also raises
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3873 questions that have no satisfactory answer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3874
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3875 However, it is easy to arrange for editing to behave consistently for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3876 questions of the form, ``What are the properties of this character?''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3877 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
3878 not implemented asking questions about where intervals start or end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3879
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
3880 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
3881 place of explicit interval boundaries. You can think of them as finding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3882 the boundaries of intervals, assuming that intervals are always
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3883 coalesced whenever possible. @xref{Property Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3884
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3885 Emacs also provides explicit intervals as a presentation feature; see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3886 @ref{Overlays}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3887
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3888 @node Substitution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3889 @section Substituting for a Character Code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3890
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3891 The following functions replace characters within a specified region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3892 based on their character codes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3893
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3894 @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
3895 @cindex replace characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3896 This function replaces all occurrences of the character @var{old-char}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3897 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
3898 defined by @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3899
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3900 @cindex undo avoidance
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
3901 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
3902 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
3903 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
3904 (@pxref{Selective Display}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3905
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3906 @code{subst-char-in-region} does not move point and returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3907 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3908
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3909 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3910 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3911 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3912 This is the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3913 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3914 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3915
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3916 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3917 (subst-char-in-region 1 20 ?i ?X)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3918 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3919
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3920 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3921 ThXs Xs the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3922 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3923 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3924 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3925 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3926
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3927 @defun translate-region start end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3928 This function applies a translation table to the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3929 buffer between positions @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3930
57646
3611af22c464 (translate-region): Document that it accepts also a
Kenichi Handa <handa@m17n.org>
parents: 57402
diff changeset
3931 The translation table @var{table} is a string or a char-table;
3611af22c464 (translate-region): Document that it accepts also a
Kenichi Handa <handa@m17n.org>
parents: 57402
diff changeset
3932 @code{(aref @var{table} @var{ochar})} gives the translated character
3611af22c464 (translate-region): Document that it accepts also a
Kenichi Handa <handa@m17n.org>
parents: 57402
diff changeset
3933 corresponding to @var{ochar}. If @var{table} is a string, any
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3934 characters with codes larger than the length of @var{table} are not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3935 altered by the translation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3937 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
3938 characters that were actually changed by the translation. This does
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
3939 not count characters that were mapped into themselves in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3940 translation table.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3941 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3942
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3943 @node Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3944 @section Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3945 @cindex registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3946
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3947 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
3948 variety of different kinds of values. Each register is named by a
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52626
diff changeset
3949 single character. All @acronym{ASCII} characters and their meta variants
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
3950 (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
3951 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
3952 Emacs Lisp by the character that is its name.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3953
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3954 @defvar register-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3955 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
3956 @var{contents})}. Normally, there is one element for each Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3957 register that has been used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3958
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3959 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
3960 register.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3961 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3962
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3963 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
3964
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3965 @table @asis
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3966 @item a number
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3967 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
3968 in the register, it converts the number to decimal.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3969
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3970 @item a marker
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3971 A marker represents a buffer position to jump to.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3972
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3973 @item a string
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3974 A string is text saved in the register.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3975
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3976 @item a rectangle
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3977 A rectangle is represented by a list of strings.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3978
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3979 @item @code{(@var{window-configuration} @var{position})}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3980 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
3981 position to jump to in the current buffer.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3982
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3983 @item @code{(@var{frame-configuration} @var{position})}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3984 This represents a frame configuration to restore, and a position
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3985 to jump to in the current buffer.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3986
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3987 @item (file @var{filename})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3988 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
3989 @var{filename}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3990
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3991 @item (file-query @var{filename} @var{position})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3992 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
3993 value visits file @var{filename} and goes to buffer position
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3994 @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
3995 confirmation first.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3996 @end table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3997
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3998 The functions in this section return unpredictable values unless
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
3999 otherwise stated.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4000
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4001 @defun get-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4002 This function returns the contents of the register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4003 @var{reg}, or @code{nil} if it has no contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4004 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4005
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4006 @defun set-register reg value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4007 This function sets the contents of register @var{reg} to @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4008 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
4009 expect only certain data types. The return value is @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4010 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4011
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4012 @deffn Command view-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4013 This command displays what is contained in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4014 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4015
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4016 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4017 @deffn Command point-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4018 This command stores both the current location of point and the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4019 buffer in register @var{reg} as a marker.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4020 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4021
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4022 @deffn Command jump-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4023 @deffnx Command register-to-point reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4024 @comment !!SourceFile register.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4025 This command restores the status recorded in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4026
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4027 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
4028 the marker. Since both the buffer and the location within the buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4029 are stored by the @code{point-to-register} function, this command can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4030 switch you to another buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4032 If @var{reg} contains a window configuration or a frame configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4033 @code{jump-to-register} restores that configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4034 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4035 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4036
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4037 @deffn Command insert-register reg &optional beforep
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4038 This command inserts contents of register @var{reg} into the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4039 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4040
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4041 Normally, this command puts point before the inserted text, and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4042 mark after it. However, if the optional second argument @var{beforep}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4043 is non-@code{nil}, it puts the mark before and point after.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4044 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
4045 function interactively by supplying any prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4046
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4047 If the register contains a rectangle, then the rectangle is inserted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4048 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
4049 in the current line and underneath it on successive lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4050
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4051 If the register contains something other than saved text (a string) or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4052 a rectangle (a list), currently useless things happen. This may be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4053 changed in the future.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4054 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4055
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4056 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4057 @deffn Command copy-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4058 This command copies the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4059 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
4060 the region from the buffer after copying it into the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4061 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4062
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4063 @deffn Command prepend-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4064 This command prepends the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4065 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
4066 the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4067 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4068
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4069 @deffn Command append-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4070 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
4071 text already in register @var{reg}. If @var{delete-flag} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4072 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
4073 to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4074 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4075
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4076 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4077 This command copies a rectangular region from @var{start} to @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4078 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
4079 deletes the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4080 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4081
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4082 @deffn Command window-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4083 This function stores the window configuration of the selected frame in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4084 register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4085 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4086
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4087 @deffn Command frame-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4088 This function stores the current frame configuration in register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4089 @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4090 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4091 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4092
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4093 @node Transposition
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4094 @section Transposition of Text
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4095
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4096 This subroutine is used by the transposition commands.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4097
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4098 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4099 This function exchanges two nonoverlapping portions of the buffer.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4100 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
4101 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
4102 other portion.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4103
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4104 Normally, @code{transpose-regions} relocates markers with the transposed
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4105 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
4106 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
4107 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
4108 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
4109 all markers unrelocated.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4110 @end defun
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4111
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4112 @node Base 64
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4113 @section Base 64 Encoding
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4114 @cindex base 64 encoding
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4115
39168
0317f0f05c37 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 38581
diff changeset
4116 Base 64 code is used in email to encode a sequence of 8-bit bytes as
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52626
diff changeset
4117 a longer sequence of @acronym{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
4118 Internet RFC@footnote{
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4119 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
4120 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
4121 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
4122 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
4123 manner.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4124 }2045. This section describes the functions for
39168
0317f0f05c37 Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 38581
diff changeset
4125 converting to and from this code.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4126
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4127 @defun base64-encode-region beg end &optional no-line-break
33911
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
4128 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
4129 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
4130 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
4131 multibyte buffer the region must contain only characters from the
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
4132 charsets @code{ascii}, @code{eight-bit-control} and
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
4133 @code{eight-bit-graphic}.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4134
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4135 Normally, this function inserts newline characters into the encoded
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4136 text, to avoid overlong lines. However, if the optional argument
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4137 @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
4138 the output is just one long line.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4139 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4140
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4141 @defun base64-encode-string string &optional no-line-break
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4142 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
4143 returns a string containing the encoded text. As for
10fd9a833957 base64 tweaks
Dave Love <fx@gnu.org>
parents: 32091
diff changeset
4144 @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
4145 string is multibyte.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4146
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4147 Normally, this function inserts newline characters into the encoded
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4148 text, to avoid overlong lines. However, if the optional argument
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4149 @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
4150 the result string is just one long line.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4151 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4152
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4153 @defun base64-decode-region beg end
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4154 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
4155 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
4156 the decoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4157
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4158 The decoding functions ignore newline characters in the encoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4159 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4160
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4161 @defun base64-decode-string string
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4162 This function converts the string @var{string} from base 64 code into
51446
a3a94326d597 base64-decode-string returns unibyte string.
Richard M. Stallman <rms@gnu.org>
parents: 50467
diff changeset
4163 the corresponding decoded text. It returns a unibyte string containing the
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4164 decoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4165
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4166 The decoding functions ignore newline characters in the encoded text.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4167 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23147
diff changeset
4168
39208
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4169 @node MD5 Checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4170 @section MD5 Checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4171 @cindex MD5 checksum
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4172 @cindex message digest computation
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4173
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4174 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
4175 ``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
4176 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
4177 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
4178 RFC@footnote{
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4179 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
4180 64}.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4181 }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
4182 message digests.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4183
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4184 @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
4185 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
4186 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
4187
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4188 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
4189 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
4190 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
4191 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
4192
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4193 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
4194 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
4195 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
4196 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
4197 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
4198 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
4199 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
4200 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
4201 information about coding systems.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4202
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4203 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
4204 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
4205 @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
4206 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
4207 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
4208 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
4209 @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
4210
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4211 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
4212 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
4213 @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
4214 coding instead.
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4215 @end defun
ad4839873265 (MD5 Checksum): New node, documents the md5 primitive.
Eli Zaretskii <eliz@gnu.org>
parents: 39168
diff changeset
4216
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4217 @node Atomic Changes
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4218 @section Atomic Change Groups
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4219 @cindex atomic changes
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4220
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4221 In data base terminology, an @dfn{atomic} change is an indivisible
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4222 change---it can succeed entirely or it can fail entirely, but it
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4223 cannot partly succeed. A Lisp program can make a series of changes to
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4224 one or several buffers as an @dfn{atomic change group}, meaning that
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4225 either the entire series of changes will be installed in their buffers
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4226 or, in case of an error, none of them will be.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4227
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4228 To do this for one buffer, the one already current, simply write a
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4229 call to @code{atomic-change-group} around the code that makes the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4230 changes, like this:
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4231
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4232 @example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4233 (atomic-change-group
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4234 (insert foo)
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4235 (delete-region x y))
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4236 @end example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4237
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4238 @noindent
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4239 If an error (or other nonlocal exit) occurs inside the body of
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4240 @code{atomic-change-group}, it unmakes all the changes in that buffer
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4241 that were during the execution of the body. This kind of change group
54916
07f4773453a0 Markup fixes.
Jesper Harder <harder@ifa.au.dk>
parents: 54480
diff changeset
4242 has no effect on any other buffers---any such changes remain.
52192
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4243
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4244 If you need something more sophisticated, such as to make changes in
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4245 various buffers constitute one atomic group, you must directly call
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4246 lower-level functions that @code{atomic-change-group} uses.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4247
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4248 @defun prepare-change-group &optional buffer
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4249 This function sets up a change group for buffer @var{buffer}, which
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4250 defaults to the current buffer. It returns a ``handle'' that
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4251 represents the change group. You must use this handle to activate the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4252 change group and subsequently to finish it.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4253 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4254
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4255 To use the change group, you must @dfn{activate} it. You must do
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4256 this before making any changes in the text of @var{buffer}.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4257
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4258 @defun activate-change-group handle
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4259 This function activates the change group that @var{handle} designates.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4260 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4261
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4262 After you activate the change group, any changes you make in that
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4263 buffer become part of it. Once you have made all the desired changes
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4264 in the buffer, you must @dfn{finish} the change group. There are two
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4265 ways to do this: you can either accept (and finalize) all the changes,
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4266 or cancel them all.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4267
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4268 @defun accept-change-group handle
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4269 This function accepts all the changes in the change group specified by
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4270 @var{handle}, making them final.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4271 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4272
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4273 @defun cancel-change-group handle
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4274 This function cancels and undoes all the changes in the change group
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4275 specified by @var{handle}.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4276 @end defun
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4277
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4278 Your code should use @code{unwind-protect} to make sure the group is
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4279 always finished. The call to @code{activate-change-group} should be
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4280 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4281 just after it runs. (This is one reason why
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4282 @code{prepare-change-group} and @code{activate-change-group} are
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4283 separate functions, because normally you would call
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4284 @code{prepare-change-group} before the start of that
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4285 @code{unwind-protect}.) Once you finish the group, don't use the
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4286 handle again---in particular, don't try to finish the same group
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4287 twice.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4288
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4289 To make a multibuffer change group, call @code{prepare-change-group}
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4290 once for each buffer you want to cover, then use @code{nconc} to
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4291 combine the returned values, like this:
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4292
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4293 @example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4294 (nconc (prepare-change-group buffer-1)
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4295 (prepare-change-group buffer-2))
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4296 @end example
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4297
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4298 You can then activate the multibuffer change group with a single call
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4299 to @code{activate-change-group}, and finish it with a single call to
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4300 @code{accept-change-group} or @code{cancel-change-group}.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4301
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4302 Nested use of several change groups for the same buffer works as you
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4303 would expect. Non-nested use of change groups for the same buffer
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4304 will get Emacs confused, so don't let it happen; the first change
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4305 group you start for any given buffer should be the last one finished.
aeb0d981dc7e (Insertion): Add insert-buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 51911
diff changeset
4306
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4307 @node Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4308 @section Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4309 @cindex change hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4310 @cindex hooks for text changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4311
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4312 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
4313 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
4314 See also @ref{Special Properties}, for how to detect changes to specific
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4315 parts of the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4316
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4317 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
4318 data if they do anything that uses regular expressions; otherwise, they
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4319 will interfere in bizarre ways with the editing operations that call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4320 them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4321
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4322 @defvar before-change-functions
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4323 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
4324 modification. Each function gets two arguments, the beginning and end
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4325 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
4326 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
4327 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4328
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4329 @defvar after-change-functions
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4330 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
4331 modification. Each function receives three arguments: the beginning and
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4332 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
4333 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
4334 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
4335
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
4336 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
4337 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
4338 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
4339 arguments.
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4340 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
4341
54120
836a9ea3b5a4 Various small changes in addition to the following:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54041
diff changeset
4342 Output of messages into the @samp{*Messages*} buffer does not
51702
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
4343 call these functions.
82502bf293e0 (Buffer Contents): Document current-word.
Richard M. Stallman <rms@gnu.org>
parents: 51446
diff changeset
4344
66149
de93c7939d28 (Change Hooks): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents: 65369
diff changeset
4345 @defmac combine-after-change-calls body@dots{}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4346 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
4347 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
4348 that seems safe.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4349
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4350 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
4351 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
4352 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
4353 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
4354 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
4355 made within the @code{combine-after-change-calls} body.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4356
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4357 @strong{Warning:} You must not alter the values of
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
4358 @code{after-change-functions} within
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4359 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
4360
52626
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52544
diff changeset
4361 @strong{Warning:} if the changes you combine occur in widely scattered
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4362 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
4363 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
4364 functions.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4365 @end defmac
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19467
diff changeset
4366
31079
ace4a0e50572 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 29102
diff changeset
4367 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
4368 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
4369 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
4370 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
4371 these functions, make it bind these variables back to their usual
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4372 values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4373
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4374 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
4375 have a function in @code{after-change-functions} or
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4376 @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
4377 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
4378 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
4379 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
4380 to call. Here is an example:
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4381
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4382 @example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4383 (setq my-own-after-change-functions nil)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4384 (defun indirect-after-change-function (beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4385 (let ((list my-own-after-change-functions))
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4386 (while list
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4387 (funcall (car list) beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4388 (setq list (cdr list)))))
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4389
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4390 @group
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4391 (add-hooks 'after-change-functions
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4392 'indirect-after-change-function)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4393 @end group
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4394 @end example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
4395
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4396 @defvar first-change-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4397 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
4398 that was previously in the unmodified state.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4399 @end defvar
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
4400
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
4401 @defvar inhibit-modification-hooks
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
4402 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
4403 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
4404 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
4405 certain special text properties (@pxref{Special Properties}) and overlay
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
4406 properties (@pxref{Overlay Properties}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25454
diff changeset
4407 @end defvar
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52192
diff changeset
4408
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52192
diff changeset
4409 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52192
diff changeset
4410 arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52192
diff changeset
4411 @end ignore