1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
58 The sorting functions described in this section all rearrange text in
59 a buffer. This is in contrast to the function `sort', which rearranges
60 the order of the elements of a list (*note Rearrangement::). The
61 values returned by these functions are not meaningful.
63 - Function: sort-subr reverse nextrecfun endrecfun &optional
65 This function is the general text-sorting routine that divides a
66 buffer into records and sorts them. Most of the commands in this
67 section use this function.
69 To understand how `sort-subr' works, consider the whole accessible
70 portion of the buffer as being divided into disjoint pieces called
71 "sort records". The records may or may not be contiguous; they may
72 not overlap. A portion of each sort record (perhaps all of it) is
73 designated as the sort key. Sorting rearranges the records in
74 order by their sort keys.
76 Usually, the records are rearranged in order of ascending sort key.
77 If the first argument to the `sort-subr' function, REVERSE, is
78 non-`nil', the sort records are rearranged in order of descending
81 The next four arguments to `sort-subr' are functions that are
82 called to move point across a sort record. They are called many
83 times from within `sort-subr'.
85 1. NEXTRECFUN is called with point at the end of a record. This
86 function moves point to the start of the next record. The
87 first record is assumed to start at the position of point
88 when `sort-subr' is called. Therefore, you should usually
89 move point to the beginning of the buffer before calling
92 This function can indicate there are no more sort records by
93 leaving point at the end of the buffer.
95 2. ENDRECFUN is called with point within a record. It moves
96 point to the end of the record.
98 3. STARTKEYFUN is called to move point from the start of a
99 record to the start of the sort key. This argument is
100 optional; if it is omitted, the whole record is the sort key.
101 If supplied, the function should either return a non-`nil'
102 value to be used as the sort key, or return `nil' to indicate
103 that the sort key is in the buffer starting at point. In the
104 latter case, ENDKEYFUN is called to find the end of the sort
107 4. ENDKEYFUN is called to move point from the start of the sort
108 key to the end of the sort key. This argument is optional.
109 If STARTKEYFUN returns `nil' and this argument is omitted (or
110 `nil'), then the sort key extends to the end of the record.
111 There is no need for ENDKEYFUN if STARTKEYFUN returns a
114 As an example of `sort-subr', here is the complete function
115 definition for `sort-lines':
117 ;; Note that the first two lines of doc string
118 ;; are effectively one line when viewed by a user.
119 (defun sort-lines (reverse start end)
120 "Sort lines in region alphabetically.
121 Called from a program, there are three arguments:
122 REVERSE (non-nil means reverse order),
123 and START and END (the region to sort)."
126 (narrow-to-region start end)
127 (goto-char (point-min))
132 Here `forward-line' moves point to the start of the next record,
133 and `end-of-line' moves point to the end of record. We do not pass
134 the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
135 is used as the sort key.
137 The `sort-paragraphs' function is very much the same, except that
138 its `sort-subr' call looks like this:
143 (skip-chars-forward "\n \t\f")))
146 - Command: sort-regexp-fields reverse record-regexp key-regexp start
148 This command sorts the region between START and END alphabetically
149 as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
150 negative integer, then sorting is in reverse order.
152 Alphabetical sorting means that two sort keys are compared by
153 comparing the first characters of each, the second characters of
154 each, and so on. If a mismatch is found, it means that the sort
155 keys are unequal; the sort key whose character is less at the
156 point of first mismatch is the lesser sort key. The individual
157 characters are compared according to their numerical values.
158 Since Emacs uses the ASCII character set, the ordering in that set
159 determines alphabetical order.
161 The value of the RECORD-REGEXP argument specifies how to divide
162 the buffer into sort records. At the end of each record, a search
163 is done for this regular expression, and the text that matches it
164 is the next record. For example, the regular expression `^.+$',
165 which matches lines with at least one character besides a newline,
166 would make each such line into a sort record. *Note Regular
167 Expressions::, for a description of the syntax and meaning of
170 The value of the KEY-REGEXP argument specifies what part of each
171 record is the sort key. The KEY-REGEXP could match the whole
172 record, or only a part. In the latter case, the rest of the
173 record has no effect on the sorted order of records, but it is
174 carried along when the record moves to its new position.
176 The KEY-REGEXP argument can refer to the text matched by a
177 subexpression of RECORD-REGEXP, or it can be a regular expression
183 then the text matched by the DIGITth `\(...\)' parenthesis
184 grouping in RECORD-REGEXP is the sort key.
187 then the whole record is the sort key.
190 then `sort-regexp-fields' searches for a match for the regular
191 expression within the record. If such a match is found, it
192 is the sort key. If there is no match for KEY-REGEXP within
193 a record then that record is ignored, which means its
194 position in the buffer is not changed. (The other records
197 For example, if you plan to sort all the lines in the region by the
198 first word on each line starting with the letter `f', you should
199 set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'. The
200 resulting expression looks like this:
202 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
206 If you call `sort-regexp-fields' interactively, it prompts for
207 RECORD-REGEXP and KEY-REGEXP in the minibuffer.
209 - Command: sort-lines reverse start end
210 This command alphabetically sorts lines in the region between
211 START and END. If REVERSE is non-`nil', the sort is in reverse
214 - Command: sort-paragraphs reverse start end
215 This command alphabetically sorts paragraphs in the region between
216 START and END. If REVERSE is non-`nil', the sort is in reverse
219 - Command: sort-pages reverse start end
220 This command alphabetically sorts pages in the region between
221 START and END. If REVERSE is non-`nil', the sort is in reverse
224 - Command: sort-fields field start end
225 This command sorts lines in the region between START and END,
226 comparing them alphabetically by the FIELDth field of each line.
227 Fields are separated by whitespace and numbered starting from 1.
228 If FIELD is negative, sorting is by the -FIELDth field from the
229 end of the line. This command is useful for sorting tables.
231 - Command: sort-numeric-fields field start end
232 This command sorts lines in the region between START and END,
233 comparing them numerically by the FIELDth field of each line. The
234 specified field must contain a number in each line of the region.
235 Fields are separated by whitespace and numbered starting from 1.
236 If FIELD is negative, sorting is by the -FIELDth field from the
237 end of the line. This command is useful for sorting tables.
239 - Command: sort-columns reverse &optional start end
240 This command sorts the lines in the region between START and END,
241 comparing them alphabetically by a certain range of columns. The
242 column positions of START and END bound the range of columns to
245 If REVERSE is non-`nil', the sort is in reverse order.
247 One unusual thing about this command is that the entire line
248 containing position START, and the entire line containing position
249 END, are included in the region sorted.
251 Note that `sort-columns' uses the `sort' utility program, and so
252 cannot work properly on text containing tab characters. Use `M-x
253 `untabify'' to convert tabs to spaces before sorting.
256 File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
261 The column functions convert between a character position (counting
262 characters from the beginning of the buffer) and a column position
263 (counting screen characters from the beginning of a line).
265 A character counts according to the number of columns it occupies on
266 the screen. This means control characters count as occupying 2 or 4
267 columns, depending upon the value of `ctl-arrow', and tabs count as
268 occupying a number of columns that depends on the value of `tab-width'
269 and on the column where the tab begins. *Note Usual Display::.
271 Column number computations ignore the width of the window and the
272 amount of horizontal scrolling. Consequently, a column value can be
273 arbitrarily high. The first (or leftmost) column is numbered 0.
275 - Function: current-column &optional buffer
276 This function returns the horizontal position of point, measured in
277 columns, counting from 0 at the left margin.
279 This is calculated by adding together the widths of all the
280 displayed representations of the character between the start of
281 the previous line and point. (e.g. control characters will have a
282 width of 2 or 4, tabs will have a variable width.)
284 Ignores the finite width of frame displaying the buffer, which
285 means that this function may return values greater than
288 Whether the line is visible (if `selective-display' is t) has no
289 effect; however, ^M is treated as end of line when
290 `selective-display' is t.
292 If BUFFER is nil, the current buffer is assumed.
294 For an example of using `current-column', see the description of
295 `count-lines' in *Note Text Lines::.
297 - Function: move-to-column column &optional force buffer
298 This function moves point to COLUMN in the current line. The
299 calculation of COLUMN takes into account the widths of the
300 displayed representations of the characters between the start of
303 If column COLUMN is beyond the end of the line, point moves to the
304 end of the line. If COLUMN is negative, point moves to the
305 beginning of the line.
307 If it is impossible to move to column COLUMN because that is in
308 the middle of a multicolumn character such as a tab, point moves
309 to the end of that character. However, if FORCE is non-`nil', and
310 COLUMN is in the middle of a tab, then `move-to-column' converts
311 the tab into spaces so that it can move precisely to column
312 COLUMN. Other multicolumn characters can cause anomalies despite
313 FORCE, since there is no way to split them.
315 The argument FORCE also has an effect if the line isn't long
316 enough to reach column COLUMN; in that case, unless the value of
317 FORCE is the special value `coerce', it says to add whitespace at
318 the end of the line to reach that column.
320 If COLUMN is not a non-negative integer, an error is signaled.
322 The return value is the column number actually moved to.
325 File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
330 The indentation functions are used to examine, move to, and change
331 whitespace that is at the beginning of a line. Some of the functions
332 can also change whitespace elsewhere on a line. Columns and indentation
333 count from zero at the left margin.
337 * Primitive Indent:: Functions used to count and insert indentation.
338 * Mode-Specific Indent:: Customize indentation for different modes.
339 * Region Indent:: Indent all the lines in a region.
340 * Relative Indent:: Indent the current line based on previous lines.
341 * Indent Tabs:: Adjustable, typewriter-like tab stops.
342 * Motion by Indent:: Move to first non-blank character.
345 File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
347 Indentation Primitives
348 ----------------------
350 This section describes the primitive functions used to count and
351 insert indentation. The functions in the following sections use these
354 - Function: current-indentation &optional buffer
355 This function returns the indentation of the current line, which is
356 the horizontal position of the first nonblank character. If the
357 contents are entirely blank, then this is the horizontal position
358 of the end of the line.
360 - Command: indent-to column &optional minimum buffer
361 This function indents from point with tabs and spaces until COLUMN
362 is reached. If MINIMUM is specified and non-`nil', then at least
363 that many spaces are inserted even if this requires going beyond
364 COLUMN. Otherwise the function does nothing if point is already
365 beyond COLUMN. The value is the column at which the inserted
366 indentation ends. If BUFFER is `nil', the current buffer is
369 - User Option: indent-tabs-mode
370 If this variable is non-`nil', indentation functions can insert
371 tabs as well as spaces. Otherwise, they insert only spaces.
372 Setting this variable automatically makes it local to the current
376 File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
378 Indentation Controlled by Major Mode
379 ------------------------------------
381 An important function of each major mode is to customize the <TAB>
382 key to indent properly for the language being edited. This section
383 describes the mechanism of the <TAB> key and how to control it. The
384 functions in this section return unpredictable values.
386 - Variable: indent-line-function
387 This variable's value is the function to be used by <TAB> (and
388 various commands) to indent the current line. The command
389 `indent-according-to-mode' does no more than call this function.
391 In Lisp mode, the value is the symbol `lisp-indent-line'; in C
392 mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
393 Fundamental mode, Text mode, and many other modes with no standard
394 for indentation, the value is `indent-to-left-margin' (which is the
397 - Command: indent-according-to-mode
398 This command calls the function in `indent-line-function' to
399 indent the current line in a way appropriate for the current major
402 - Command: indent-for-tab-command &optional prefix-arg
403 This command calls the function in `indent-line-function' to indent
404 the current line; except that if that function is
405 `indent-to-left-margin', it calls `insert-tab' instead. (That is
406 a trivial command that inserts a tab character.)
408 - Command: newline-and-indent
409 This function inserts a newline, then indents the new line (the one
410 following the newline just inserted) according to the major mode.
412 It does indentation by calling the current `indent-line-function'.
413 In programming language modes, this is the same thing <TAB> does,
414 but in some text modes, where <TAB> inserts a tab,
415 `newline-and-indent' indents to the column specified by
418 - Command: reindent-then-newline-and-indent
419 This command reindents the current line, inserts a newline at
420 point, and then reindents the new line (the one following the
421 newline just inserted).
423 This command does indentation on both lines according to the
424 current major mode, by calling the current value of
425 `indent-line-function'. In programming language modes, this is
426 the same thing <TAB> does, but in some text modes, where <TAB>
427 inserts a tab, `reindent-then-newline-and-indent' indents to the
428 column specified by `left-margin'.
431 File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
433 Indenting an Entire Region
434 --------------------------
436 This section describes commands that indent all the lines in the
437 region. They return unpredictable values.
439 - Command: indent-region start end to-column
440 This command indents each nonblank line starting between START
441 (inclusive) and END (exclusive). If TO-COLUMN is `nil',
442 `indent-region' indents each nonblank line by calling the current
443 mode's indentation function, the value of `indent-line-function'.
445 If TO-COLUMN is non-`nil', it should be an integer specifying the
446 number of columns of indentation; then this function gives each
447 line exactly that much indentation, by either adding or deleting
450 If there is a fill prefix, `indent-region' indents each line by
451 making it start with the fill prefix.
453 - Variable: indent-region-function
454 The value of this variable is a function that can be used by
455 `indent-region' as a short cut. You should design the function so
456 that it will produce the same results as indenting the lines of the
457 region one by one, but presumably faster.
459 If the value is `nil', there is no short cut, and `indent-region'
460 actually works line by line.
462 A short-cut function is useful in modes such as C mode and Lisp
463 mode, where the `indent-line-function' must scan from the
464 beginning of the function definition: applying it to each line
465 would be quadratic in time. The short cut can update the scan
466 information as it moves through the lines indenting them; this
467 takes linear time. In a mode where indenting a line individually
468 is fast, there is no need for a short cut.
470 `indent-region' with a non-`nil' argument TO-COLUMN has a
471 different meaning and does not use this variable.
473 - Command: indent-rigidly start end count
474 This command indents all lines starting between START (inclusive)
475 and END (exclusive) sideways by COUNT columns. This "preserves
476 the shape" of the affected region, moving it as a rigid unit.
477 Consequently, this command is useful not only for indenting
478 regions of unindented text, but also for indenting regions of
481 For example, if COUNT is 3, this command adds 3 columns of
482 indentation to each of the lines beginning in the region specified.
484 In Mail mode, `C-c C-y' (`mail-yank-original') uses
485 `indent-rigidly' to indent the text copied from the message being
488 - Command: indent-code-rigidly start end columns &optional
490 This is like `indent-rigidly', except that it doesn't alter lines
491 that start within strings or comments.
493 In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
494 the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
497 File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
499 Indentation Relative to Previous Lines
500 --------------------------------------
502 This section describes two commands that indent the current line
503 based on the contents of previous lines.
505 - Command: indent-relative &optional unindented-ok
506 This command inserts whitespace at point, extending to the same
507 column as the next "indent point" of the previous nonblank line.
508 An indent point is a non-whitespace character following
509 whitespace. The next indent point is the first one at a column
510 greater than the current column of point. For example, if point
511 is underneath and to the left of the first non-blank character of
512 a line of text, it moves to that column by inserting whitespace.
514 If the previous nonblank line has no next indent point (i.e., none
515 at a great enough column position), `indent-relative' either does
516 nothing (if UNINDENTED-OK is non-`nil') or calls
517 `tab-to-tab-stop'. Thus, if point is underneath and to the right
518 of the last column of a short line of text, this command ordinarily
519 moves point to the next tab stop by inserting whitespace.
521 The return value of `indent-relative' is unpredictable.
523 In the following example, point is at the beginning of the second
526 This line is indented twelve spaces.
527 -!-The quick brown fox jumped.
529 Evaluation of the expression `(indent-relative nil)' produces the
532 This line is indented twelve spaces.
533 -!-The quick brown fox jumped.
535 In this example, point is between the `m' and `p' of `jumped':
537 This line is indented twelve spaces.
538 The quick brown fox jum-!-ped.
540 Evaluation of the expression `(indent-relative nil)' produces the
543 This line is indented twelve spaces.
544 The quick brown fox jum -!-ped.
546 - Command: indent-relative-maybe
547 This command indents the current line like the previous nonblank
548 line. It calls `indent-relative' with `t' as the UNINDENTED-OK
549 argument. The return value is unpredictable.
551 If the previous nonblank line has no indent points beyond the
552 current column, this command does nothing.
555 File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
557 Adjustable "Tab Stops"
558 ----------------------
560 This section explains the mechanism for user-specified "tab stops"
561 and the mechanisms that use and set them. The name "tab stops" is used
562 because the feature is similar to that of the tab stops on a
563 typewriter. The feature works by inserting an appropriate number of
564 spaces and tab characters to reach the next tab stop column; it does not
565 affect the display of tab characters in the buffer (*note Usual
566 Display::). Note that the <TAB> character as input uses this tab stop
567 feature only in a few major modes, such as Text mode.
569 - Command: tab-to-tab-stop
570 This command inserts spaces or tabs up to the next tab stop column
571 defined by `tab-stop-list'. It searches the list for an element
572 greater than the current column number, and uses that element as
573 the column to indent to. It does nothing if no such element is
576 - User Option: tab-stop-list
577 This variable is the list of tab stop columns used by
578 `tab-to-tab-stops'. The elements should be integers in increasing
579 order. The tab stop columns need not be evenly spaced.
581 Use `M-x edit-tab-stops' to edit the location of tab stops
585 File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
587 Indentation-Based Motion Commands
588 ---------------------------------
590 These commands, primarily for interactive use, act based on the
591 indentation in the text.
593 - Command: back-to-indentation
594 This command moves point to the first non-whitespace character in
595 the current line (which is the line in which point is located).
598 - Command: backward-to-indentation arg
599 This command moves point backward ARG lines and then to the first
600 nonblank character on that line. It returns `nil'.
602 - Command: forward-to-indentation arg
603 This command moves point forward ARG lines and then to the first
604 nonblank character on that line. It returns `nil'.
607 File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
612 The case change commands described here work on text in the current
613 buffer. *Note Character Case::, for case conversion commands that work
614 on strings and characters. *Note Case Tables::, for how to customize
615 which characters are upper or lower case and how to convert them.
617 - Command: capitalize-region start end &optional buffer
618 This function capitalizes all words in the region defined by START
619 and END. To capitalize means to convert each word's first
620 character to upper case and convert the rest of each word to lower
621 case. The function returns `nil'.
623 If one end of the region is in the middle of a word, the part of
624 the word within the region is treated as an entire word.
626 When `capitalize-region' is called interactively, START and END
627 are point and the mark, with the smallest first.
629 ---------- Buffer: foo ----------
630 This is the contents of the 5th foo.
631 ---------- Buffer: foo ----------
633 (capitalize-region 1 44)
636 ---------- Buffer: foo ----------
637 This Is The Contents Of The 5th Foo.
638 ---------- Buffer: foo ----------
640 - Command: downcase-region start end &optional buffer
641 This function converts all of the letters in the region defined by
642 START and END to lower case. The function returns `nil'.
644 When `downcase-region' is called interactively, START and END are
645 point and the mark, with the smallest first.
647 - Command: upcase-region start end &optional buffer
648 This function converts all of the letters in the region defined by
649 START and END to upper case. The function returns `nil'.
651 When `upcase-region' is called interactively, START and END are
652 point and the mark, with the smallest first.
654 - Command: capitalize-word count &optional buffer
655 This function capitalizes COUNT words after point, moving point
656 over as it does. To capitalize means to convert each word's first
657 character to upper case and convert the rest of each word to lower
658 case. If COUNT is negative, the function capitalizes the -COUNT
659 previous words but does not move point. The value is `nil'.
661 If point is in the middle of a word, the part of the word before
662 point is ignored when moving forward. The rest is treated as an
665 When `capitalize-word' is called interactively, COUNT is set to
666 the numeric prefix argument.
668 - Command: downcase-word count &optional buffer
669 This function converts the COUNT words after point to all lower
670 case, moving point over as it does. If COUNT is negative, it
671 converts the -COUNT previous words but does not move point. The
674 When `downcase-word' is called interactively, COUNT is set to the
675 numeric prefix argument.
677 - Command: upcase-word count &optional buffer
678 This function converts the COUNT words after point to all upper
679 case, moving point over as it does. If COUNT is negative, it
680 converts the -COUNT previous words but does not move point. The
683 When `upcase-word' is called interactively, COUNT is set to the
684 numeric prefix argument.
687 File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
692 Text properties are an alternative interface to extents (*note
693 Extents::), and are built on top of them. They are useful when you
694 want to view textual properties as being attached to the characters
695 themselves rather than to intervals of characters. The text property
696 interface is compatible with FSF Emacs.
698 Each character position in a buffer or a string can have a "text
699 property list", much like the property list of a symbol (*note Property
700 Lists::). The properties belong to a particular character at a
701 particular place, such as, the letter `T' at the beginning of this
702 sentence or the first `o' in `foo'--if the same character occurs in two
703 different places, the two occurrences generally have different
706 Each property has a name and a value. Both of these can be any Lisp
707 object, but the name is normally a symbol. The usual way to access the
708 property list is to specify a name and ask what value corresponds to it.
710 Note that FSF Emacs also looks at the `category' property to find
711 defaults for text properties. We consider this too bogus to implement.
713 Copying text between strings and buffers preserves the properties
714 along with the characters; this includes such diverse functions as
715 `substring', `insert', and `buffer-substring'.
719 * Examining Properties:: Looking at the properties of one character.
720 * Changing Properties:: Setting the properties of a range of text.
721 * Property Search:: Searching for where a property changes value.
722 * Special Properties:: Particular properties with special meanings.
723 * Saving Properties:: Saving text properties in files, and reading
727 File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
729 Examining Text Properties
730 -------------------------
732 The simplest way to examine text properties is to ask for the value
733 of a particular property of a particular character. For that, use
734 `get-text-property'. Use `text-properties-at' to get the entire
735 property list of a character. *Note Property Search::, for functions
736 to examine the properties of a number of characters at once.
738 These functions handle both strings and buffers. (Keep in mind that
739 positions in a string start from 0, whereas positions in a buffer start
742 - Function: get-text-property pos prop &optional object at-flag
743 This function returns the value of the PROP property of the
744 character after position POS in OBJECT (a buffer or string). The
745 argument OBJECT is optional and defaults to the current buffer.
747 - Function: get-char-property pos prop &optional object at-flag
748 This function is like `get-text-property', except that it checks
749 all extents, not just text-property extents.
752 - Function: text-properties-at position &optional object
753 This function returns the entire property list of the character at
754 POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
755 defaults to the current buffer.
757 - Variable: default-text-properties
758 This variable holds a property list giving default values for text
759 properties. Whenever a character does not specify a value for a
760 property, the value stored in this list is used instead. Here is
763 (setq default-text-properties '(foo 69))
764 ;; Make sure character 1 has no properties of its own.
765 (set-text-properties 1 2 nil)
766 ;; What we get, when we ask, is the default value.
767 (get-text-property 1 'foo)
771 File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
773 Changing Text Properties
774 ------------------------
776 The primitives for changing properties apply to a specified range of
777 text. The function `set-text-properties' (see end of section) sets the
778 entire property list of the text in that range; more often, it is
779 useful to add, change, or delete just certain properties specified by
782 Since text properties are considered part of the buffer's contents,
783 and can affect how the buffer looks on the screen, any change in the
784 text properties is considered a buffer modification. Buffer text
785 property changes are undoable (*note Undo::).
787 - Function: put-text-property start end prop value &optional object
788 This function sets the PROP property to VALUE for the text between
789 START and END in the string or buffer OBJECT. If OBJECT is `nil',
790 it defaults to the current buffer.
792 - Function: add-text-properties start end props &optional object
793 This function modifies the text properties for the text between
794 START and END in the string or buffer OBJECT. If OBJECT is `nil',
795 it defaults to the current buffer.
797 The argument PROPS specifies which properties to change. It
798 should have the form of a property list (*note Property Lists::):
799 a list whose elements include the property names followed
800 alternately by the corresponding values.
802 The return value is `t' if the function actually changed some
803 property's value; `nil' otherwise (if PROPS is `nil' or its values
804 agree with those in the text).
806 For example, here is how to set the `comment' and `face'
807 properties of a range of text:
809 (add-text-properties START END
810 '(comment t face highlight))
812 - Function: remove-text-properties start end props &optional object
813 This function deletes specified text properties from the text
814 between START and END in the string or buffer OBJECT. If OBJECT
815 is `nil', it defaults to the current buffer.
817 The argument PROPS specifies which properties to delete. It
818 should have the form of a property list (*note Property Lists::):
819 a list whose elements are property names alternating with
820 corresponding values. But only the names matter--the values that
821 accompany them are ignored. For example, here's how to remove the
824 (remove-text-properties START END '(face nil))
826 The return value is `t' if the function actually changed some
827 property's value; `nil' otherwise (if PROPS is `nil' or if no
828 character in the specified text had any of those properties).
830 - Function: set-text-properties start end props &optional object
831 This function completely replaces the text property list for the
832 text between START and END in the string or buffer OBJECT. If
833 OBJECT is `nil', it defaults to the current buffer.
835 The argument PROPS is the new property list. It should be a list
836 whose elements are property names alternating with corresponding
839 After `set-text-properties' returns, all the characters in the
840 specified range have identical properties.
842 If PROPS is `nil', the effect is to get rid of all properties from
843 the specified range of text. Here's an example:
845 (set-text-properties START END nil)
847 See also the function `buffer-substring-without-properties' (*note
848 Buffer Contents::) which copies text from the buffer but does not copy
852 File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
854 Property Search Functions
855 -------------------------
857 In typical use of text properties, most of the time several or many
858 consecutive characters have the same value for a property. Rather than
859 writing your programs to examine characters one by one, it is much
860 faster to process chunks of text that have the same property value.
862 Here are functions you can use to do this. They use `eq' for
863 comparing property values. In all cases, OBJECT defaults to the
866 For high performance, it's very important to use the LIMIT argument
867 to these functions, especially the ones that search for a single
868 property--otherwise, they may spend a long time scanning to the end of
869 the buffer, if the property you are interested in does not change.
871 Remember that a position is always between two characters; the
872 position returned by these functions is between two characters with
873 different properties.
875 - Function: next-property-change pos &optional object limit
876 The function scans the text forward from position POS in the
877 string or buffer OBJECT till it finds a change in some text
878 property, then returns the position of the change. In other
879 words, it returns the position of the first character beyond POS
880 whose properties are not identical to those of the character just
883 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
884 there is no property change before that point,
885 `next-property-change' returns LIMIT.
887 The value is `nil' if the properties remain unchanged all the way
888 to the end of OBJECT and LIMIT is `nil'. If the value is
889 non-`nil', it is a position greater than or equal to POS. The
890 value equals POS only when LIMIT equals POS.
892 Here is an example of how to scan the buffer by chunks of text
893 within which all properties are constant:
896 (let ((plist (text-properties-at (point)))
898 (or (next-property-change (point) (current-buffer))
900 Process text from point to NEXT-CHANGE...
901 (goto-char next-change)))
903 - Function: next-single-property-change pos prop &optional object limit
904 The function scans the text forward from position POS in the
905 string or buffer OBJECT till it finds a change in the PROP
906 property, then returns the position of the change. In other
907 words, it returns the position of the first character beyond POS
908 whose PROP property differs from that of the character just after
911 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
912 there is no property change before that point,
913 `next-single-property-change' returns LIMIT.
915 The value is `nil' if the property remains unchanged all the way to
916 the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
917 it is a position greater than or equal to POS; it equals POS only
920 - Function: previous-property-change pos &optional object limit
921 This is like `next-property-change', but scans backward from POS
922 instead of forward. If the value is non-`nil', it is a position
923 less than or equal to POS; it equals POS only if LIMIT equals POS.
925 - Function: previous-single-property-change pos prop &optional object
927 This is like `next-single-property-change', but scans backward from
928 POS instead of forward. If the value is non-`nil', it is a
929 position less than or equal to POS; it equals POS only if LIMIT
932 - Function: text-property-any start end prop value &optional object
933 This function returns non-`nil' if at least one character between
934 START and END has a property PROP whose value is VALUE. More
935 precisely, it returns the position of the first such character.
936 Otherwise, it returns `nil'.
938 The optional fifth argument, OBJECT, specifies the string or
939 buffer to scan. Positions are relative to OBJECT. The default
940 for OBJECT is the current buffer.
942 - Function: text-property-not-all start end prop value &optional object
943 This function returns non-`nil' if at least one character between
944 START and END has a property PROP whose value differs from VALUE.
945 More precisely, it returns the position of the first such
946 character. Otherwise, it returns `nil'.
948 The optional fifth argument, OBJECT, specifies the string or
949 buffer to scan. Positions are relative to OBJECT. The default
950 for OBJECT is the current buffer.
953 File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
955 Properties with Special Meanings
956 --------------------------------
958 The predefined properties are the same as those for extents. *Note
962 File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
964 Saving Text Properties in Files
965 -------------------------------
967 You can save text properties in files, and restore text properties
968 when inserting the files, using these two hooks:
970 - Variable: write-region-annotate-functions
971 This variable's value is a list of functions for `write-region' to
972 run to encode text properties in some fashion as annotations to
973 the text being written in the file. *Note Writing to Files::.
975 Each function in the list is called with two arguments: the start
976 and end of the region to be written. These functions should not
977 alter the contents of the buffer. Instead, they should return
978 lists indicating annotations to write in the file in addition to
979 the text in the buffer.
981 Each function should return a list of elements of the form
982 `(POSITION . STRING)', where POSITION is an integer specifying the
983 relative position in the text to be written, and STRING is the
984 annotation to add there.
986 Each list returned by one of these functions must be already
987 sorted in increasing order by POSITION. If there is more than one
988 function, `write-region' merges the lists destructively into one
991 When `write-region' actually writes the text from the buffer to the
992 file, it intermixes the specified annotations at the corresponding
993 positions. All this takes place without modifying the buffer.
995 - Variable: after-insert-file-functions
996 This variable holds a list of functions for `insert-file-contents'
997 to call after inserting a file's contents. These functions should
998 scan the inserted text for annotations, and convert them to the
999 text properties they stand for.
1001 Each function receives one argument, the length of the inserted
1002 text; point indicates the start of that text. The function should
1003 scan that text for annotations, delete them, and create the text
1004 properties that the annotations specify. The function should
1005 return the updated length of the inserted text, as it stands after
1006 those changes. The value returned by one function becomes the
1007 argument to the next function.
1009 These functions should always return with point at the beginning of
1012 The intended use of `after-insert-file-functions' is for converting
1013 some sort of textual annotations into actual text properties. But
1014 other uses may be possible.
1016 We invite users to write Lisp programs to store and retrieve text
1017 properties in files, using these hooks, and thus to experiment with
1018 various data formats and find good ones. Eventually we hope users will
1019 produce good, general extensions we can install in Emacs.
1021 We suggest not trying to handle arbitrary Lisp objects as property
1022 names or property values--because a program that general is probably
1023 difficult to write, and slow. Instead, choose a set of possible data
1024 types that are reasonably flexible, and not too hard to encode.
1026 *Note Format Conversion::, for a related feature.
1029 File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
1031 Substituting for a Character Code
1032 =================================
1034 The following functions replace characters within a specified region
1035 based on their character codes.
1037 - Function: subst-char-in-region start end old-char new-char &optional
1039 This function replaces all occurrences of the character OLD-CHAR
1040 with the character NEW-CHAR in the region of the current buffer
1041 defined by START and END.
1043 If NOUNDO is non-`nil', then `subst-char-in-region' does not
1044 record the change for undo and does not mark the buffer as
1045 modified. This feature is used for controlling selective display
1046 (*note Selective Display::).
1048 `subst-char-in-region' does not move point and returns `nil'.
1050 ---------- Buffer: foo ----------
1051 This is the contents of the buffer before.
1052 ---------- Buffer: foo ----------
1054 (subst-char-in-region 1 20 ?i ?X)
1057 ---------- Buffer: foo ----------
1058 ThXs Xs the contents of the buffer before.
1059 ---------- Buffer: foo ----------
1061 - Function: translate-region start end table
1062 This function applies a translation table to the characters in the
1063 buffer between positions START and END. The translation table
1064 TABLE can be either a string, a vector, or a char-table.
1066 If TABLE is a string, its Nth element is the mapping for the
1067 character with code N.
1069 If TABLE is a vector, its Nth element is the mapping for character
1070 with code N. Legal mappings are characters, strings, or `nil'
1071 (meaning don't replace.)
1073 If TABLE is a char-table, its elements describe the mapping
1074 between characters and their replacements. The char-table should
1075 be of type `char' or `generic'.
1077 When the TABLE is a string or vector and its length is less than
1078 the total number of characters (256 without Mule), any characters
1079 with codes larger than the length of TABLE are not altered by the
1082 The return value of `translate-region' is the number of characters
1083 that were actually changed by the translation. This does not
1084 count characters that were mapped into themselves in the
1087 *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
1088 to be a string. This is still the case in FSF Emacs.
1090 The following example creates a char-table that is passed to
1091 `translate-region', which translates character `a' to `the letter
1092 a', removes character `b', and translates character `c' to newline.
1094 ---------- Buffer: foo ----------
1095 Here is a sentence in the buffer.
1096 ---------- Buffer: foo ----------
1098 (let ((table (make-char-table 'generic)))
1099 (put-char-table ?a "the letter a" table)
1100 (put-char-table ?b "" table)
1101 (put-char-table ?c ?\n table)
1102 (translate-region (point-min) (point-max) table))
1105 ---------- Buffer: foo ----------
1106 Here is the letter a senten
1108 ---------- Buffer: foo ----------
1111 File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
1116 A register is a sort of variable used in XEmacs editing that can
1117 hold a marker, a string, a rectangle, a window configuration (of one
1118 frame), or a frame configuration (of all frames). Each register is
1119 named by a single character. All characters, including control and
1120 meta characters (but with the exception of `C-g'), can be used to name
1121 registers. Thus, there are 255 possible registers. A register is
1122 designated in Emacs Lisp by a character that is its name.
1124 The functions in this section return unpredictable values unless
1127 - Variable: register-alist
1128 This variable is an alist of elements of the form `(NAME .
1129 CONTENTS)'. Normally, there is one element for each XEmacs
1130 register that has been used.
1132 The object NAME is a character (an integer) identifying the
1133 register. The object CONTENTS is a string, marker, or list
1134 representing the register contents. A string represents text
1135 stored in the register. A marker represents a position. A list
1136 represents a rectangle; its elements are strings, one per line of
1139 - Function: get-register register
1140 This function returns the contents of the register REGISTER, or
1141 `nil' if it has no contents.
1143 - Function: set-register register value
1144 This function sets the contents of register REGISTER to VALUE. A
1145 register can be set to any value, but the other register functions
1146 expect only certain data types. The return value is VALUE.
1148 - Command: view-register register
1149 This command displays what is contained in register REGISTER.
1151 - Command: insert-register register &optional beforep
1152 This command inserts contents of register REGISTER into the current
1155 Normally, this command puts point before the inserted text, and the
1156 mark after it. However, if the optional second argument BEFOREP
1157 is non-`nil', it puts the mark before and point after. You can
1158 pass a non-`nil' second argument BEFOREP to this function
1159 interactively by supplying any prefix argument.
1161 If the register contains a rectangle, then the rectangle is
1162 inserted with its upper left corner at point. This means that
1163 text is inserted in the current line and underneath it on
1166 If the register contains something other than saved text (a
1167 string) or a rectangle (a list), currently useless things happen.
1168 This may be changed in the future.
1171 File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
1173 Transposition of Text
1174 =====================
1176 This subroutine is used by the transposition commands.
1178 - Function: transpose-regions start1 end1 start2 end2 &optional
1180 This function exchanges two nonoverlapping portions of the buffer.
1181 Arguments START1 and END1 specify the bounds of one portion and
1182 arguments START2 and END2 specify the bounds of the other portion.
1184 Normally, `transpose-regions' relocates markers with the transposed
1185 text; a marker previously positioned within one of the two
1186 transposed portions moves along with that portion, thus remaining
1187 between the same two characters in their new position. However,
1188 if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
1189 this--it leaves all markers unrelocated.
projects / chise / xemacs-chise.git- / blob