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