1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
55 Internals of the Kill Ring
56 --------------------------
58 The variable `kill-ring' holds the kill ring contents, in the form
59 of a list of strings. The most recent kill is always at the front of
62 The `kill-ring-yank-pointer' variable points to a link in the kill
63 ring list, whose CAR is the text to yank next. We say it identifies
64 the "front" of the ring. Moving `kill-ring-yank-pointer' to a
65 different link is called "rotating the kill ring". We call the kill
66 ring a "ring" because the functions that move the yank pointer wrap
67 around from the end of the list to the beginning, or vice-versa.
68 Rotation of the kill ring is virtual; it does not change the value of
71 Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
72 whose values are normally lists. The word "pointer" in the name of the
73 `kill-ring-yank-pointer' indicates that the variable's purpose is to
74 identify one element of the list for use by the next yank command.
76 The value of `kill-ring-yank-pointer' is always `eq' to one of the
77 links in the kill ring list. The element it identifies is the CAR of
78 that link. Kill commands, which change the kill ring, also set this
79 variable to the value of `kill-ring'. The effect is to rotate the ring
80 so that the newly killed text is at the front.
82 Here is a diagram that shows the variable `kill-ring-yank-pointer'
83 pointing to the second entry in the kill ring `("some text" "a
84 different piece of text" "yet older text")'.
86 kill-ring kill-ring-yank-pointer
88 | ___ ___ ---> ___ ___ ___ ___
89 --> |___|___|------> |___|___|--> |___|___|--> nil
92 | | -->"yet older text"
94 | --> "a different piece of text"
98 This state of affairs might occur after `C-y' (`yank') immediately
99 followed by `M-y' (`yank-pop').
101 - Variable: kill-ring
102 This variable holds the list of killed text sequences, most
103 recently killed first.
105 - Variable: kill-ring-yank-pointer
106 This variable's value indicates which element of the kill ring is
107 at the "front" of the ring for yanking. More precisely, the value
108 is a tail of the value of `kill-ring', and its CAR is the kill
109 string that `C-y' should yank.
111 - User Option: kill-ring-max
112 The value of this variable is the maximum length to which the kill
113 ring can grow, before elements are thrown away at the end. The
114 default value for `kill-ring-max' is 30.
117 File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
122 Most buffers have an "undo list", which records all changes made to
123 the buffer's text so that they can be undone. (The buffers that don't
124 have one are usually special-purpose buffers for which XEmacs assumes
125 that undoing is not useful.) All the primitives that modify the text
126 in the buffer automatically add elements to the front of the undo list,
127 which is in the variable `buffer-undo-list'.
129 - Variable: buffer-undo-list
130 This variable's value is the undo list of the current buffer. A
131 value of `t' disables the recording of undo information.
133 Here are the kinds of elements an undo list can have:
136 This kind of element records a previous value of point. Ordinary
137 cursor motion does not get any sort of undo record, but deletion
138 commands use these entries to record where point was before the
142 This kind of element indicates how to delete text that was
143 inserted. Upon insertion, the text occupied the range BEG-END in
147 This kind of element indicates how to reinsert text that was
148 deleted. The deleted text itself is the string TEXT. The place to
149 reinsert it is `(abs POSITION)'.
152 This kind of element indicates that an unmodified buffer became
153 modified. The elements HIGH and LOW are two integers, each
154 recording 16 bits of the visited file's modification time as of
155 when it was previously visited or saved. `primitive-undo' uses
156 those values to determine whether to mark the buffer as unmodified
157 once again; it does so only if the file's modification time
158 matches those numbers.
160 `(nil PROPERTY VALUE BEG . END)'
161 This kind of element records a change in a text property. Here's
162 how you might undo the change:
164 (put-text-property BEG END PROPERTY VALUE)
167 This element indicates where point was at an earlier time.
168 Undoing this element sets point to POSITION. Deletion normally
169 creates an element of this kind as well as a reinsertion element.
172 This element is a boundary. The elements between two boundaries
173 are called a "change group"; normally, each change group
174 corresponds to one keyboard command, and undo commands normally
175 undo an entire group as a unit.
177 - Function: undo-boundary
178 This function places a boundary element in the undo list. The undo
179 command stops at such a boundary, and successive undo commands undo
180 to earlier and earlier boundaries. This function returns `nil'.
182 The editor command loop automatically creates an undo boundary
183 before each key sequence is executed. Thus, each undo normally
184 undoes the effects of one command. Self-inserting input
185 characters are an exception. The command loop makes a boundary
186 for the first such character; the next 19 consecutive
187 self-inserting input characters do not make boundaries, and then
188 the 20th does, and so on as long as self-inserting characters
191 All buffer modifications add a boundary whenever the previous
192 undoable change was made in some other buffer. This way, a
193 command that modifies several buffers makes a boundary in each
196 Calling this function explicitly is useful for splitting the
197 effects of a command into more than one unit. For example,
198 `query-replace' calls `undo-boundary' after each replacement, so
199 that the user can undo individual replacements one by one.
201 - Function: primitive-undo count list
202 This is the basic function for undoing elements of an undo list.
203 It undoes the first COUNT elements of LIST, returning the rest of
204 LIST. You could write this function in Lisp, but it is convenient
207 `primitive-undo' adds elements to the buffer's undo list when it
208 changes the buffer. Undo commands avoid confusion by saving the
209 undo list value at the beginning of a sequence of undo operations.
210 Then the undo operations use and update the saved value. The new
211 elements added by undoing are not part of this saved value, so
212 they don't interfere with continuing to undo.
215 File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
217 Maintaining Undo Lists
218 ======================
220 This section describes how to enable and disable undo information for
221 a given buffer. It also explains how the undo list is truncated
222 automatically so it doesn't get too big.
224 Recording of undo information in a newly created buffer is normally
225 enabled to start with; but if the buffer name starts with a space, the
226 undo recording is initially disabled. You can explicitly enable or
227 disable undo recording with the following two functions, or by setting
228 `buffer-undo-list' yourself.
230 - Command: buffer-enable-undo &optional buffer-or-name
231 This command enables recording undo information for buffer
232 BUFFER-OR-NAME, so that subsequent changes can be undone. If no
233 argument is supplied, then the current buffer is used. This
234 function does nothing if undo recording is already enabled in the
235 buffer. It returns `nil'.
237 In an interactive call, BUFFER-OR-NAME is the current buffer. You
238 cannot specify any other buffer.
240 - Function: buffer-disable-undo &optional buffer
241 - Function: buffer-flush-undo &optional buffer
242 This function discards the undo list of BUFFER, and disables
243 further recording of undo information. As a result, it is no
244 longer possible to undo either previous changes or any subsequent
245 changes. If the undo list of BUFFER is already disabled, this
246 function has no effect.
248 This function returns `nil'. It cannot be called interactively.
250 The name `buffer-flush-undo' is not considered obsolete, but the
251 preferred name `buffer-disable-undo' is new as of Emacs versions
254 As editing continues, undo lists get longer and longer. To prevent
255 them from using up all available memory space, garbage collection trims
256 them back to size limits you can set. (For this purpose, the "size" of
257 an undo list measures the cons cells that make up the list, plus the
258 strings of deleted text.) Two variables control the range of acceptable
259 sizes: `undo-limit' and `undo-strong-limit'.
261 - Variable: undo-limit
262 This is the soft limit for the acceptable size of an undo list.
263 The change group at which this size is exceeded is the last one
266 - Variable: undo-strong-limit
267 This is the upper limit for the acceptable size of an undo list.
268 The change group at which this size is exceeded is discarded
269 itself (along with all older change groups). There is one
270 exception: the very latest change group is never discarded no
271 matter how big it is.
274 File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
279 "Filling" means adjusting the lengths of lines (by moving the line
280 breaks) so that they are nearly (but no greater than) a specified
281 maximum width. Additionally, lines can be "justified", which means
282 inserting spaces to make the left and/or right margins line up
283 precisely. The width is controlled by the variable `fill-column'. For
284 ease of reading, lines should be no longer than 70 or so columns.
286 You can use Auto Fill mode (*note Auto Filling::) to fill text
287 automatically as you insert it, but changes to existing text may leave
288 it improperly filled. Then you must fill the text explicitly.
290 Most of the commands in this section return values that are not
291 meaningful. All the functions that do filling take note of the current
292 left margin, current right margin, and current justification style
293 (*note Margins::). If the current justification style is `none', the
294 filling functions don't actually do anything.
296 Several of the filling functions have an argument JUSTIFY. If it is
297 non-`nil', that requests some kind of justification. It can be `left',
298 `right', `full', or `center', to request a specific style of
299 justification. If it is `t', that means to use the current
300 justification style for this part of the text (see
301 `current-justification', below).
303 When you call the filling functions interactively, using a prefix
304 argument implies the value `full' for JUSTIFY.
306 - Command: fill-paragraph justify
307 This command fills the paragraph at or after point. If JUSTIFY is
308 non-`nil', each line is justified as well. It uses the ordinary
309 paragraph motion commands to find paragraph boundaries. *Note
310 Paragraphs: (xemacs)Paragraphs.
312 - Command: fill-region start end &optional justify
313 This command fills each of the paragraphs in the region from START
314 to END. It justifies as well if JUSTIFY is non-`nil'.
316 The variable `paragraph-separate' controls how to distinguish
317 paragraphs. *Note Standard Regexps::.
319 - Command: fill-individual-paragraphs start end &optional justify
321 This command fills each paragraph in the region according to its
322 individual fill prefix. Thus, if the lines of a paragraph were
323 indented with spaces, the filled paragraph will remain indented in
326 The first two arguments, START and END, are the beginning and end
327 of the region to be filled. The third and fourth arguments,
328 JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
329 paragraphs are justified as well as filled. If MAIL-FLAG is
330 non-`nil', it means the function is operating on a mail message
331 and therefore should not fill the header lines.
333 Ordinarily, `fill-individual-paragraphs' regards each change in
334 indentation as starting a new paragraph. If
335 `fill-individual-varying-indent' is non-`nil', then only separator
336 lines separate paragraphs. That mode can handle indented
337 paragraphs with additional indentation on the first line.
339 - User Option: fill-individual-varying-indent
340 This variable alters the action of `fill-individual-paragraphs' as
343 - Command: fill-region-as-paragraph start end &optional justify
344 This command considers a region of text as a paragraph and fills
345 it. If the region was made up of many paragraphs, the blank lines
346 between paragraphs are removed. This function justifies as well
347 as filling when JUSTIFY is non-`nil'.
349 In an interactive call, any prefix argument requests justification.
351 In Adaptive Fill mode, which is enabled by default,
352 `fill-region-as-paragraph' on an indented paragraph when there is
353 no fill prefix uses the indentation of the second line of the
354 paragraph as the fill prefix.
356 - Command: justify-current-line how eop nosqueeze
357 This command inserts spaces between the words of the current line
358 so that the line ends exactly at `fill-column'. It returns `nil'.
360 The argument HOW, if non-`nil' specifies explicitly the style of
361 justification. It can be `left', `right', `full', `center', or
362 `none'. If it is `t', that means to do follow specified
363 justification style (see `current-justification', below). `nil'
364 means to do full justification.
366 If EOP is non-`nil', that means do left-justification when
367 `current-justification' specifies full justification. This is used
368 for the last line of a paragraph; even if the paragraph as a whole
369 is fully justified, the last line should not be.
371 If NOSQUEEZE is non-`nil', that means do not change interior
374 - User Option: default-justification
375 This variable's value specifies the style of justification to use
376 for text that doesn't specify a style with a text property. The
377 possible values are `left', `right', `full', `center', or `none'.
378 The default value is `left'.
380 - Function: current-justification
381 This function returns the proper justification style to use for
382 filling the text around point.
384 - Variable: fill-paragraph-function
385 This variable provides a way for major modes to override the
386 filling of paragraphs. If the value is non-`nil',
387 `fill-paragraph' calls this function to do the work. If the
388 function returns a non-`nil' value, `fill-paragraph' assumes the
389 job is done, and immediately returns that value.
391 The usual use of this feature is to fill comments in programming
392 language modes. If the function needs to fill a paragraph in the
393 usual way, it can do so as follows:
395 (let ((fill-paragraph-function nil))
396 (fill-paragraph arg))
398 - Variable: use-hard-newlines
399 If this variable is non-`nil', the filling functions do not delete
400 newlines that have the `hard' text property. These "hard
401 newlines" act as paragraph separators.
404 File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
409 - User Option: fill-prefix
410 This variable specifies a string of text that appears at the
411 beginning of normal text lines and should be disregarded when
412 filling them. Any line that fails to start with the fill prefix
413 is considered the start of a paragraph; so is any line that starts
414 with the fill prefix followed by additional whitespace. Lines
415 that start with the fill prefix but no additional whitespace are
416 ordinary text lines that can be filled together. The resulting
417 filled lines also start with the fill prefix.
419 The fill prefix follows the left margin whitespace, if any.
421 - User Option: fill-column
422 This buffer-local variable specifies the maximum width of filled
423 lines. Its value should be an integer, which is a number of
424 columns. All the filling, justification and centering commands
425 are affected by this variable, including Auto Fill mode (*note
428 As a practical matter, if you are writing text for other people to
429 read, you should set `fill-column' to no more than 70. Otherwise
430 the line will be too long for people to read comfortably, and this
431 can make the text seem clumsy.
433 - Variable: default-fill-column
434 The value of this variable is the default value for `fill-column'
435 in buffers that do not override it. This is the same as
436 `(default-value 'fill-column)'.
438 The default value for `default-fill-column' is 70.
440 - Command: set-left-margin from to margin
441 This sets the `left-margin' property on the text from FROM to TO
442 to the value MARGIN. If Auto Fill mode is enabled, this command
443 also refills the region to fit the new margin.
445 - Command: set-right-margin from to margin
446 This sets the `right-margin' property on the text from FROM to TO
447 to the value MARGIN. If Auto Fill mode is enabled, this command
448 also refills the region to fit the new margin.
450 - Function: current-left-margin
451 This function returns the proper left margin value to use for
452 filling the text around point. The value is the sum of the
453 `left-margin' property of the character at the start of the
454 current line (or zero if none), and the value of the variable
457 - Function: current-fill-column
458 This function returns the proper fill column value to use for
459 filling the text around point. The value is the value of the
460 `fill-column' variable, minus the value of the `right-margin'
461 property of the character after point.
463 - Command: move-to-left-margin &optional n force
464 This function moves point to the left margin of the current line.
465 The column moved to is determined by calling the function
466 `current-left-margin'. If the argument N is non-`nil',
467 `move-to-left-margin' moves forward N-1 lines first.
469 If FORCE is non-`nil', that says to fix the line's indentation if
470 that doesn't match the left margin value.
472 - Function: delete-to-left-margin from to
473 This function removes left margin indentation from the text
474 between FROM and TO. The amount of indentation to delete is
475 determined by calling `current-left-margin'. In no case does this
476 function delete non-whitespace.
478 - Function: indent-to-left-margin
479 This is the default `indent-line-function', used in Fundamental
480 mode, Text mode, etc. Its effect is to adjust the indentation at
481 the beginning of the current line to the value specified by the
482 variable `left-margin'. This may involve either inserting or
485 - Variable: left-margin
486 This variable specifies the base left margin column. In
487 Fundamental mode, <LFD> indents to this column. This variable
488 automatically becomes buffer-local when set in any fashion.
491 File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
496 Auto Fill mode is a minor mode that fills lines automatically as text
497 is inserted. This section describes the hook used by Auto Fill mode.
498 For a description of functions that you can call explicitly to fill and
499 justify existing text, see *Note Filling::.
501 Auto Fill mode also enables the functions that change the margins and
502 justification style to refill portions of the text. *Note Margins::.
504 - Variable: auto-fill-function
505 The value of this variable should be a function (of no arguments)
506 to be called after self-inserting a space or a newline. It may be
507 `nil', in which case nothing special is done in that case.
509 The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
510 mode is enabled. That is a function whose sole purpose is to
511 implement the usual strategy for breaking a line.
513 In older Emacs versions, this variable was named
514 `auto-fill-hook', but since it is not called with the
515 standard convention for hooks, it was renamed to
516 `auto-fill-function' in version 19.
519 File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
524 The sorting functions described in this section all rearrange text in
525 a buffer. This is in contrast to the function `sort', which rearranges
526 the order of the elements of a list (*note Rearrangement::). The
527 values returned by these functions are not meaningful.
529 - Function: sort-subr reverse nextrecfun endrecfun &optional
530 startkeyfun endkeyfun
531 This function is the general text-sorting routine that divides a
532 buffer into records and sorts them. Most of the commands in this
533 section use this function.
535 To understand how `sort-subr' works, consider the whole accessible
536 portion of the buffer as being divided into disjoint pieces called
537 "sort records". The records may or may not be contiguous; they may
538 not overlap. A portion of each sort record (perhaps all of it) is
539 designated as the sort key. Sorting rearranges the records in
540 order by their sort keys.
542 Usually, the records are rearranged in order of ascending sort key.
543 If the first argument to the `sort-subr' function, REVERSE, is
544 non-`nil', the sort records are rearranged in order of descending
547 The next four arguments to `sort-subr' are functions that are
548 called to move point across a sort record. They are called many
549 times from within `sort-subr'.
551 1. NEXTRECFUN is called with point at the end of a record. This
552 function moves point to the start of the next record. The
553 first record is assumed to start at the position of point
554 when `sort-subr' is called. Therefore, you should usually
555 move point to the beginning of the buffer before calling
558 This function can indicate there are no more sort records by
559 leaving point at the end of the buffer.
561 2. ENDRECFUN is called with point within a record. It moves
562 point to the end of the record.
564 3. STARTKEYFUN is called to move point from the start of a
565 record to the start of the sort key. This argument is
566 optional; if it is omitted, the whole record is the sort key.
567 If supplied, the function should either return a non-`nil'
568 value to be used as the sort key, or return `nil' to indicate
569 that the sort key is in the buffer starting at point. In the
570 latter case, ENDKEYFUN is called to find the end of the sort
573 4. ENDKEYFUN is called to move point from the start of the sort
574 key to the end of the sort key. This argument is optional.
575 If STARTKEYFUN returns `nil' and this argument is omitted (or
576 `nil'), then the sort key extends to the end of the record.
577 There is no need for ENDKEYFUN if STARTKEYFUN returns a
580 As an example of `sort-subr', here is the complete function
581 definition for `sort-lines':
583 ;; Note that the first two lines of doc string
584 ;; are effectively one line when viewed by a user.
585 (defun sort-lines (reverse beg end)
586 "Sort lines in region alphabetically.
587 Called from a program, there are three arguments:
588 REVERSE (non-nil means reverse order),
589 and BEG and END (the region to sort)."
592 (narrow-to-region beg end)
593 (goto-char (point-min))
598 Here `forward-line' moves point to the start of the next record,
599 and `end-of-line' moves point to the end of record. We do not pass
600 the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
601 is used as the sort key.
603 The `sort-paragraphs' function is very much the same, except that
604 its `sort-subr' call looks like this:
609 (skip-chars-forward "\n \t\f")))
612 - Command: sort-regexp-fields reverse record-regexp key-regexp start
614 This command sorts the region between START and END alphabetically
615 as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
616 negative integer, then sorting is in reverse order.
618 Alphabetical sorting means that two sort keys are compared by
619 comparing the first characters of each, the second characters of
620 each, and so on. If a mismatch is found, it means that the sort
621 keys are unequal; the sort key whose character is less at the
622 point of first mismatch is the lesser sort key. The individual
623 characters are compared according to their numerical values.
624 Since Emacs uses the ASCII character set, the ordering in that set
625 determines alphabetical order.
627 The value of the RECORD-REGEXP argument specifies how to divide
628 the buffer into sort records. At the end of each record, a search
629 is done for this regular expression, and the text that matches it
630 is the next record. For example, the regular expression `^.+$',
631 which matches lines with at least one character besides a newline,
632 would make each such line into a sort record. *Note Regular
633 Expressions::, for a description of the syntax and meaning of
636 The value of the KEY-REGEXP argument specifies what part of each
637 record is the sort key. The KEY-REGEXP could match the whole
638 record, or only a part. In the latter case, the rest of the
639 record has no effect on the sorted order of records, but it is
640 carried along when the record moves to its new position.
642 The KEY-REGEXP argument can refer to the text matched by a
643 subexpression of RECORD-REGEXP, or it can be a regular expression
649 then the text matched by the DIGITth `\(...\)' parenthesis
650 grouping in RECORD-REGEXP is the sort key.
653 then the whole record is the sort key.
656 then `sort-regexp-fields' searches for a match for the regular
657 expression within the record. If such a match is found, it
658 is the sort key. If there is no match for KEY-REGEXP within
659 a record then that record is ignored, which means its
660 position in the buffer is not changed. (The other records
663 For example, if you plan to sort all the lines in the region by the
664 first word on each line starting with the letter `f', you should
665 set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'. The
666 resulting expression looks like this:
668 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
672 If you call `sort-regexp-fields' interactively, it prompts for
673 RECORD-REGEXP and KEY-REGEXP in the minibuffer.
675 - Command: sort-lines reverse start end
676 This command alphabetically sorts lines in the region between
677 START and END. If REVERSE is non-`nil', the sort is in reverse
680 - Command: sort-paragraphs reverse start end
681 This command alphabetically sorts paragraphs in the region between
682 START and END. If REVERSE is non-`nil', the sort is in reverse
685 - Command: sort-pages reverse start end
686 This command alphabetically sorts pages in the region between
687 START and END. If REVERSE is non-`nil', the sort is in reverse
690 - Command: sort-fields field start end
691 This command sorts lines in the region between START and END,
692 comparing them alphabetically by the FIELDth field of each line.
693 Fields are separated by whitespace and numbered starting from 1.
694 If FIELD is negative, sorting is by the -FIELDth field from the
695 end of the line. This command is useful for sorting tables.
697 - Command: sort-numeric-fields field start end
698 This command sorts lines in the region between START and END,
699 comparing them numerically by the FIELDth field of each line. The
700 specified field must contain a number in each line of the region.
701 Fields are separated by whitespace and numbered starting from 1.
702 If FIELD is negative, sorting is by the -FIELDth field from the
703 end of the line. This command is useful for sorting tables.
705 - Command: sort-columns reverse &optional beg end
706 This command sorts the lines in the region between BEG and END,
707 comparing them alphabetically by a certain range of columns. The
708 column positions of BEG and END bound the range of columns to sort
711 If REVERSE is non-`nil', the sort is in reverse order.
713 One unusual thing about this command is that the entire line
714 containing position BEG, and the entire line containing position
715 END, are included in the region sorted.
717 Note that `sort-columns' uses the `sort' utility program, and so
718 cannot work properly on text containing tab characters. Use `M-x
719 `untabify'' to convert tabs to spaces before sorting.
722 File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
727 The column functions convert between a character position (counting
728 characters from the beginning of the buffer) and a column position
729 (counting screen characters from the beginning of a line).
731 A character counts according to the number of columns it occupies on
732 the screen. This means control characters count as occupying 2 or 4
733 columns, depending upon the value of `ctl-arrow', and tabs count as
734 occupying a number of columns that depends on the value of `tab-width'
735 and on the column where the tab begins. *Note Usual Display::.
737 Column number computations ignore the width of the window and the
738 amount of horizontal scrolling. Consequently, a column value can be
739 arbitrarily high. The first (or leftmost) column is numbered 0.
741 - Function: current-column
742 This function returns the horizontal position of point, measured in
743 columns, counting from 0 at the left margin. The column position
744 is the sum of the widths of all the displayed representations of
745 the characters between the start of the current line and point.
747 For an example of using `current-column', see the description of
748 `count-lines' in *Note Text Lines::.
750 - Function: move-to-column column &optional force
751 This function moves point to COLUMN in the current line. The
752 calculation of COLUMN takes into account the widths of the
753 displayed representations of the characters between the start of
756 If column COLUMN is beyond the end of the line, point moves to the
757 end of the line. If COLUMN is negative, point moves to the
758 beginning of the line.
760 If it is impossible to move to column COLUMN because that is in
761 the middle of a multicolumn character such as a tab, point moves
762 to the end of that character. However, if FORCE is non-`nil', and
763 COLUMN is in the middle of a tab, then `move-to-column' converts
764 the tab into spaces so that it can move precisely to column
765 COLUMN. Other multicolumn characters can cause anomalies despite
766 FORCE, since there is no way to split them.
768 The argument FORCE also has an effect if the line isn't long
769 enough to reach column COLUMN; in that case, it says to add
770 whitespace at the end of the line to reach that column.
772 If COLUMN is not an integer, an error is signaled.
774 The return value is the column number actually moved to.
777 File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
782 The indentation functions are used to examine, move to, and change
783 whitespace that is at the beginning of a line. Some of the functions
784 can also change whitespace elsewhere on a line. Columns and indentation
785 count from zero at the left margin.
789 * Primitive Indent:: Functions used to count and insert indentation.
790 * Mode-Specific Indent:: Customize indentation for different modes.
791 * Region Indent:: Indent all the lines in a region.
792 * Relative Indent:: Indent the current line based on previous lines.
793 * Indent Tabs:: Adjustable, typewriter-like tab stops.
794 * Motion by Indent:: Move to first non-blank character.
797 File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
799 Indentation Primitives
800 ----------------------
802 This section describes the primitive functions used to count and
803 insert indentation. The functions in the following sections use these
806 - Function: current-indentation
807 This function returns the indentation of the current line, which is
808 the horizontal position of the first nonblank character. If the
809 contents are entirely blank, then this is the horizontal position
810 of the end of the line.
812 - Command: indent-to column &optional minimum
813 This function indents from point with tabs and spaces until COLUMN
814 is reached. If MINIMUM is specified and non-`nil', then at least
815 that many spaces are inserted even if this requires going beyond
816 COLUMN. Otherwise the function does nothing if point is already
817 beyond COLUMN. The value is the column at which the inserted
820 - User Option: indent-tabs-mode
821 If this variable is non-`nil', indentation functions can insert
822 tabs as well as spaces. Otherwise, they insert only spaces.
823 Setting this variable automatically makes it local to the current
827 File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
829 Indentation Controlled by Major Mode
830 ------------------------------------
832 An important function of each major mode is to customize the <TAB>
833 key to indent properly for the language being edited. This section
834 describes the mechanism of the <TAB> key and how to control it. The
835 functions in this section return unpredictable values.
837 - Variable: indent-line-function
838 This variable's value is the function to be used by <TAB> (and
839 various commands) to indent the current line. The command
840 `indent-according-to-mode' does no more than call this function.
842 In Lisp mode, the value is the symbol `lisp-indent-line'; in C
843 mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
844 Fundamental mode, Text mode, and many other modes with no standard
845 for indentation, the value is `indent-to-left-margin' (which is the
848 - Command: indent-according-to-mode
849 This command calls the function in `indent-line-function' to
850 indent the current line in a way appropriate for the current major
853 - Command: indent-for-tab-command
854 This command calls the function in `indent-line-function' to indent
855 the current line; except that if that function is
856 `indent-to-left-margin', it calls `insert-tab' instead. (That is
857 a trivial command that inserts a tab character.)
859 - Command: newline-and-indent
860 This function inserts a newline, then indents the new line (the one
861 following the newline just inserted) according to the major mode.
863 It does indentation by calling the current `indent-line-function'.
864 In programming language modes, this is the same thing <TAB> does,
865 but in some text modes, where <TAB> inserts a tab,
866 `newline-and-indent' indents to the column specified by
869 - Command: reindent-then-newline-and-indent
870 This command reindents the current line, inserts a newline at
871 point, and then reindents the new line (the one following the
872 newline just inserted).
874 This command does indentation on both lines according to the
875 current major mode, by calling the current value of
876 `indent-line-function'. In programming language modes, this is
877 the same thing <TAB> does, but in some text modes, where <TAB>
878 inserts a tab, `reindent-then-newline-and-indent' indents to the
879 column specified by `left-margin'.
882 File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
884 Indenting an Entire Region
885 --------------------------
887 This section describes commands that indent all the lines in the
888 region. They return unpredictable values.
890 - Command: indent-region start end to-column
891 This command indents each nonblank line starting between START
892 (inclusive) and END (exclusive). If TO-COLUMN is `nil',
893 `indent-region' indents each nonblank line by calling the current
894 mode's indentation function, the value of `indent-line-function'.
896 If TO-COLUMN is non-`nil', it should be an integer specifying the
897 number of columns of indentation; then this function gives each
898 line exactly that much indentation, by either adding or deleting
901 If there is a fill prefix, `indent-region' indents each line by
902 making it start with the fill prefix.
904 - Variable: indent-region-function
905 The value of this variable is a function that can be used by
906 `indent-region' as a short cut. You should design the function so
907 that it will produce the same results as indenting the lines of the
908 region one by one, but presumably faster.
910 If the value is `nil', there is no short cut, and `indent-region'
911 actually works line by line.
913 A short-cut function is useful in modes such as C mode and Lisp
914 mode, where the `indent-line-function' must scan from the
915 beginning of the function definition: applying it to each line
916 would be quadratic in time. The short cut can update the scan
917 information as it moves through the lines indenting them; this
918 takes linear time. In a mode where indenting a line individually
919 is fast, there is no need for a short cut.
921 `indent-region' with a non-`nil' argument TO-COLUMN has a
922 different meaning and does not use this variable.
924 - Command: indent-rigidly start end count
925 This command indents all lines starting between START (inclusive)
926 and END (exclusive) sideways by COUNT columns. This "preserves
927 the shape" of the affected region, moving it as a rigid unit.
928 Consequently, this command is useful not only for indenting
929 regions of unindented text, but also for indenting regions of
932 For example, if COUNT is 3, this command adds 3 columns of
933 indentation to each of the lines beginning in the region specified.
935 In Mail mode, `C-c C-y' (`mail-yank-original') uses
936 `indent-rigidly' to indent the text copied from the message being
939 - Function: indent-code-rigidly start end columns &optional
941 This is like `indent-rigidly', except that it doesn't alter lines
942 that start within strings or comments.
944 In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
945 the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
948 File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
950 Indentation Relative to Previous Lines
951 --------------------------------------
953 This section describes two commands that indent the current line
954 based on the contents of previous lines.
956 - Command: indent-relative &optional unindented-ok
957 This command inserts whitespace at point, extending to the same
958 column as the next "indent point" of the previous nonblank line.
959 An indent point is a non-whitespace character following
960 whitespace. The next indent point is the first one at a column
961 greater than the current column of point. For example, if point
962 is underneath and to the left of the first non-blank character of
963 a line of text, it moves to that column by inserting whitespace.
965 If the previous nonblank line has no next indent point (i.e., none
966 at a great enough column position), `indent-relative' either does
967 nothing (if UNINDENTED-OK is non-`nil') or calls
968 `tab-to-tab-stop'. Thus, if point is underneath and to the right
969 of the last column of a short line of text, this command ordinarily
970 moves point to the next tab stop by inserting whitespace.
972 The return value of `indent-relative' is unpredictable.
974 In the following example, point is at the beginning of the second
977 This line is indented twelve spaces.
978 -!-The quick brown fox jumped.
980 Evaluation of the expression `(indent-relative nil)' produces the
983 This line is indented twelve spaces.
984 -!-The quick brown fox jumped.
986 In this example, point is between the `m' and `p' of `jumped':
988 This line is indented twelve spaces.
989 The quick brown fox jum-!-ped.
991 Evaluation of the expression `(indent-relative nil)' produces the
994 This line is indented twelve spaces.
995 The quick brown fox jum -!-ped.
997 - Command: indent-relative-maybe
998 This command indents the current line like the previous nonblank
999 line. It calls `indent-relative' with `t' as the UNINDENTED-OK
1000 argument. The return value is unpredictable.
1002 If the previous nonblank line has no indent points beyond the
1003 current column, this command does nothing.
1006 File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
1008 Adjustable "Tab Stops"
1009 ----------------------
1011 This section explains the mechanism for user-specified "tab stops"
1012 and the mechanisms that use and set them. The name "tab stops" is used
1013 because the feature is similar to that of the tab stops on a
1014 typewriter. The feature works by inserting an appropriate number of
1015 spaces and tab characters to reach the next tab stop column; it does not
1016 affect the display of tab characters in the buffer (*note Usual
1017 Display::). Note that the <TAB> character as input uses this tab stop
1018 feature only in a few major modes, such as Text mode.
1020 - Command: tab-to-tab-stop
1021 This command inserts spaces or tabs up to the next tab stop column
1022 defined by `tab-stop-list'. It searches the list for an element
1023 greater than the current column number, and uses that element as
1024 the column to indent to. It does nothing if no such element is
1027 - User Option: tab-stop-list
1028 This variable is the list of tab stop columns used by
1029 `tab-to-tab-stops'. The elements should be integers in increasing
1030 order. The tab stop columns need not be evenly spaced.
1032 Use `M-x edit-tab-stops' to edit the location of tab stops
1036 File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
1038 Indentation-Based Motion Commands
1039 ---------------------------------
1041 These commands, primarily for interactive use, act based on the
1042 indentation in the text.
1044 - Command: back-to-indentation
1045 This command moves point to the first non-whitespace character in
1046 the current line (which is the line in which point is located).
1049 - Command: backward-to-indentation arg
1050 This command moves point backward ARG lines and then to the first
1051 nonblank character on that line. It returns `nil'.
1053 - Command: forward-to-indentation arg
1054 This command moves point forward ARG lines and then to the first
1055 nonblank character on that line. It returns `nil'.
1058 File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
1063 The case change commands described here work on text in the current
1064 buffer. *Note Character Case::, for case conversion commands that work
1065 on strings and characters. *Note Case Tables::, for how to customize
1066 which characters are upper or lower case and how to convert them.
1068 - Command: capitalize-region start end
1069 This function capitalizes all words in the region defined by START
1070 and END. To capitalize means to convert each word's first
1071 character to upper case and convert the rest of each word to lower
1072 case. The function returns `nil'.
1074 If one end of the region is in the middle of a word, the part of
1075 the word within the region is treated as an entire word.
1077 When `capitalize-region' is called interactively, START and END
1078 are point and the mark, with the smallest first.
1080 ---------- Buffer: foo ----------
1081 This is the contents of the 5th foo.
1082 ---------- Buffer: foo ----------
1084 (capitalize-region 1 44)
1087 ---------- Buffer: foo ----------
1088 This Is The Contents Of The 5th Foo.
1089 ---------- Buffer: foo ----------
1091 - Command: downcase-region start end
1092 This function converts all of the letters in the region defined by
1093 START and END to lower case. The function returns `nil'.
1095 When `downcase-region' is called interactively, START and END are
1096 point and the mark, with the smallest first.
1098 - Command: upcase-region start end
1099 This function converts all of the letters in the region defined by
1100 START and END to upper case. The function returns `nil'.
1102 When `upcase-region' is called interactively, START and END are
1103 point and the mark, with the smallest first.
1105 - Command: capitalize-word count
1106 This function capitalizes COUNT words after point, moving point
1107 over as it does. To capitalize means to convert each word's first
1108 character to upper case and convert the rest of each word to lower
1109 case. If COUNT is negative, the function capitalizes the -COUNT
1110 previous words but does not move point. The value is `nil'.
1112 If point is in the middle of a word, the part of the word before
1113 point is ignored when moving forward. The rest is treated as an
1116 When `capitalize-word' is called interactively, COUNT is set to
1117 the numeric prefix argument.
1119 - Command: downcase-word count
1120 This function converts the COUNT words after point to all lower
1121 case, moving point over as it does. If COUNT is negative, it
1122 converts the -COUNT previous words but does not move point. The
1125 When `downcase-word' is called interactively, COUNT is set to the
1126 numeric prefix argument.
1128 - Command: upcase-word count
1129 This function converts the COUNT words after point to all upper
1130 case, moving point over as it does. If COUNT is negative, it
1131 converts the -COUNT previous words but does not move point. The
1134 When `upcase-word' is called interactively, COUNT is set to the
1135 numeric prefix argument.
1138 File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
1143 Text properties are an alternative interface to extents (*note
1144 Extents::), and are built on top of them. They are useful when you
1145 want to view textual properties as being attached to the characters
1146 themselves rather than to intervals of characters. The text property
1147 interface is compatible with FSF Emacs.
1149 Each character position in a buffer or a string can have a "text
1150 property list", much like the property list of a symbol (*note Property
1151 Lists::). The properties belong to a particular character at a
1152 particular place, such as, the letter `T' at the beginning of this
1153 sentence or the first `o' in `foo'--if the same character occurs in two
1154 different places, the two occurrences generally have different
1157 Each property has a name and a value. Both of these can be any Lisp
1158 object, but the name is normally a symbol. The usual way to access the
1159 property list is to specify a name and ask what value corresponds to it.
1161 Note that FSF Emacs also looks at the `category' property to find
1162 defaults for text properties. We consider this too bogus to implement.
1164 Copying text between strings and buffers preserves the properties
1165 along with the characters; this includes such diverse functions as
1166 `substring', `insert', and `buffer-substring'.
1170 * Examining Properties:: Looking at the properties of one character.
1171 * Changing Properties:: Setting the properties of a range of text.
1172 * Property Search:: Searching for where a property changes value.
1173 * Special Properties:: Particular properties with special meanings.
1174 * Saving Properties:: Saving text properties in files, and reading
projects / chise / xemacs-chise.git / blob