1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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 beg 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 BEG and END (the region to sort)."
126 (narrow-to-region beg 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 BEG END
240 This command sorts the lines in the region between BEG and END,
241 comparing them alphabetically by a certain range of columns. The
242 column positions of BEG and END bound the range of columns to sort
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 BEG, 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
276 This function returns the horizontal position of point, measured in
277 columns, counting from 0 at the left margin. The column position
278 is the sum of the widths of all the displayed representations of
279 the characters between the start of the current line and point.
281 For an example of using `current-column', see the description of
282 `count-lines' in *Note Text Lines::.
284 - Function: move-to-column COLUMN &optional FORCE
285 This function moves point to COLUMN in the current line. The
286 calculation of COLUMN takes into account the widths of the
287 displayed representations of the characters between the start of
290 If column COLUMN is beyond the end of the line, point moves to the
291 end of the line. If COLUMN is negative, point moves to the
292 beginning of the line.
294 If it is impossible to move to column COLUMN because that is in
295 the middle of a multicolumn character such as a tab, point moves
296 to the end of that character. However, if FORCE is non-`nil', and
297 COLUMN is in the middle of a tab, then `move-to-column' converts
298 the tab into spaces so that it can move precisely to column
299 COLUMN. Other multicolumn characters can cause anomalies despite
300 FORCE, since there is no way to split them.
302 The argument FORCE also has an effect if the line isn't long
303 enough to reach column COLUMN; in that case, it says to add
304 whitespace at the end of the line to reach that column.
306 If COLUMN is not an integer, an error is signaled.
308 The return value is the column number actually moved to.
311 File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
316 The indentation functions are used to examine, move to, and change
317 whitespace that is at the beginning of a line. Some of the functions
318 can also change whitespace elsewhere on a line. Columns and indentation
319 count from zero at the left margin.
323 * Primitive Indent:: Functions used to count and insert indentation.
324 * Mode-Specific Indent:: Customize indentation for different modes.
325 * Region Indent:: Indent all the lines in a region.
326 * Relative Indent:: Indent the current line based on previous lines.
327 * Indent Tabs:: Adjustable, typewriter-like tab stops.
328 * Motion by Indent:: Move to first non-blank character.
331 File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
333 Indentation Primitives
334 ----------------------
336 This section describes the primitive functions used to count and
337 insert indentation. The functions in the following sections use these
340 - Function: current-indentation
341 This function returns the indentation of the current line, which is
342 the horizontal position of the first nonblank character. If the
343 contents are entirely blank, then this is the horizontal position
344 of the end of the line.
346 - Command: indent-to COLUMN &optional MINIMUM
347 This function indents from point with tabs and spaces until COLUMN
348 is reached. If MINIMUM is specified and non-`nil', then at least
349 that many spaces are inserted even if this requires going beyond
350 COLUMN. Otherwise the function does nothing if point is already
351 beyond COLUMN. The value is the column at which the inserted
354 - User Option: indent-tabs-mode
355 If this variable is non-`nil', indentation functions can insert
356 tabs as well as spaces. Otherwise, they insert only spaces.
357 Setting this variable automatically makes it local to the current
361 File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
363 Indentation Controlled by Major Mode
364 ------------------------------------
366 An important function of each major mode is to customize the <TAB>
367 key to indent properly for the language being edited. This section
368 describes the mechanism of the <TAB> key and how to control it. The
369 functions in this section return unpredictable values.
371 - Variable: indent-line-function
372 This variable's value is the function to be used by <TAB> (and
373 various commands) to indent the current line. The command
374 `indent-according-to-mode' does no more than call this function.
376 In Lisp mode, the value is the symbol `lisp-indent-line'; in C
377 mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
378 Fundamental mode, Text mode, and many other modes with no standard
379 for indentation, the value is `indent-to-left-margin' (which is the
382 - Command: indent-according-to-mode
383 This command calls the function in `indent-line-function' to
384 indent the current line in a way appropriate for the current major
387 - Command: indent-for-tab-command
388 This command calls the function in `indent-line-function' to indent
389 the current line; except that if that function is
390 `indent-to-left-margin', it calls `insert-tab' instead. (That is
391 a trivial command that inserts a tab character.)
393 - Command: newline-and-indent
394 This function inserts a newline, then indents the new line (the one
395 following the newline just inserted) according to the major mode.
397 It does indentation by calling the current `indent-line-function'.
398 In programming language modes, this is the same thing <TAB> does,
399 but in some text modes, where <TAB> inserts a tab,
400 `newline-and-indent' indents to the column specified by
403 - Command: reindent-then-newline-and-indent
404 This command reindents the current line, inserts a newline at
405 point, and then reindents the new line (the one following the
406 newline just inserted).
408 This command does indentation on both lines according to the
409 current major mode, by calling the current value of
410 `indent-line-function'. In programming language modes, this is
411 the same thing <TAB> does, but in some text modes, where <TAB>
412 inserts a tab, `reindent-then-newline-and-indent' indents to the
413 column specified by `left-margin'.
416 File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
418 Indenting an Entire Region
419 --------------------------
421 This section describes commands that indent all the lines in the
422 region. They return unpredictable values.
424 - Command: indent-region START END TO-COLUMN
425 This command indents each nonblank line starting between START
426 (inclusive) and END (exclusive). If TO-COLUMN is `nil',
427 `indent-region' indents each nonblank line by calling the current
428 mode's indentation function, the value of `indent-line-function'.
430 If TO-COLUMN is non-`nil', it should be an integer specifying the
431 number of columns of indentation; then this function gives each
432 line exactly that much indentation, by either adding or deleting
435 If there is a fill prefix, `indent-region' indents each line by
436 making it start with the fill prefix.
438 - Variable: indent-region-function
439 The value of this variable is a function that can be used by
440 `indent-region' as a short cut. You should design the function so
441 that it will produce the same results as indenting the lines of the
442 region one by one, but presumably faster.
444 If the value is `nil', there is no short cut, and `indent-region'
445 actually works line by line.
447 A short-cut function is useful in modes such as C mode and Lisp
448 mode, where the `indent-line-function' must scan from the
449 beginning of the function definition: applying it to each line
450 would be quadratic in time. The short cut can update the scan
451 information as it moves through the lines indenting them; this
452 takes linear time. In a mode where indenting a line individually
453 is fast, there is no need for a short cut.
455 `indent-region' with a non-`nil' argument TO-COLUMN has a
456 different meaning and does not use this variable.
458 - Command: indent-rigidly START END COUNT
459 This command indents all lines starting between START (inclusive)
460 and END (exclusive) sideways by COUNT columns. This "preserves
461 the shape" of the affected region, moving it as a rigid unit.
462 Consequently, this command is useful not only for indenting
463 regions of unindented text, but also for indenting regions of
466 For example, if COUNT is 3, this command adds 3 columns of
467 indentation to each of the lines beginning in the region specified.
469 In Mail mode, `C-c C-y' (`mail-yank-original') uses
470 `indent-rigidly' to indent the text copied from the message being
473 - Function: indent-code-rigidly START END COLUMNS &optional
475 This is like `indent-rigidly', except that it doesn't alter lines
476 that start within strings or comments.
478 In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
479 the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
482 File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
484 Indentation Relative to Previous Lines
485 --------------------------------------
487 This section describes two commands that indent the current line
488 based on the contents of previous lines.
490 - Command: indent-relative &optional UNINDENTED-OK
491 This command inserts whitespace at point, extending to the same
492 column as the next "indent point" of the previous nonblank line.
493 An indent point is a non-whitespace character following
494 whitespace. The next indent point is the first one at a column
495 greater than the current column of point. For example, if point
496 is underneath and to the left of the first non-blank character of
497 a line of text, it moves to that column by inserting whitespace.
499 If the previous nonblank line has no next indent point (i.e., none
500 at a great enough column position), `indent-relative' either does
501 nothing (if UNINDENTED-OK is non-`nil') or calls
502 `tab-to-tab-stop'. Thus, if point is underneath and to the right
503 of the last column of a short line of text, this command ordinarily
504 moves point to the next tab stop by inserting whitespace.
506 The return value of `indent-relative' is unpredictable.
508 In the following example, point is at the beginning of the second
511 This line is indented twelve spaces.
512 -!-The quick brown fox jumped.
514 Evaluation of the expression `(indent-relative nil)' produces the
517 This line is indented twelve spaces.
518 -!-The quick brown fox jumped.
520 In this example, point is between the `m' and `p' of `jumped':
522 This line is indented twelve spaces.
523 The quick brown fox jum-!-ped.
525 Evaluation of the expression `(indent-relative nil)' produces the
528 This line is indented twelve spaces.
529 The quick brown fox jum -!-ped.
531 - Command: indent-relative-maybe
532 This command indents the current line like the previous nonblank
533 line. It calls `indent-relative' with `t' as the UNINDENTED-OK
534 argument. The return value is unpredictable.
536 If the previous nonblank line has no indent points beyond the
537 current column, this command does nothing.
540 File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
542 Adjustable "Tab Stops"
543 ----------------------
545 This section explains the mechanism for user-specified "tab stops"
546 and the mechanisms that use and set them. The name "tab stops" is used
547 because the feature is similar to that of the tab stops on a
548 typewriter. The feature works by inserting an appropriate number of
549 spaces and tab characters to reach the next tab stop column; it does not
550 affect the display of tab characters in the buffer (*note Usual
551 Display::.). Note that the <TAB> character as input uses this tab stop
552 feature only in a few major modes, such as Text mode.
554 - Command: tab-to-tab-stop
555 This command inserts spaces or tabs up to the next tab stop column
556 defined by `tab-stop-list'. It searches the list for an element
557 greater than the current column number, and uses that element as
558 the column to indent to. It does nothing if no such element is
561 - User Option: tab-stop-list
562 This variable is the list of tab stop columns used by
563 `tab-to-tab-stops'. The elements should be integers in increasing
564 order. The tab stop columns need not be evenly spaced.
566 Use `M-x edit-tab-stops' to edit the location of tab stops
570 File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
572 Indentation-Based Motion Commands
573 ---------------------------------
575 These commands, primarily for interactive use, act based on the
576 indentation in the text.
578 - Command: back-to-indentation
579 This command moves point to the first non-whitespace character in
580 the current line (which is the line in which point is located).
583 - Command: backward-to-indentation ARG
584 This command moves point backward ARG lines and then to the first
585 nonblank character on that line. It returns `nil'.
587 - Command: forward-to-indentation ARG
588 This command moves point forward ARG lines and then to the first
589 nonblank character on that line. It returns `nil'.
592 File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
597 The case change commands described here work on text in the current
598 buffer. *Note Character Case::, for case conversion commands that work
599 on strings and characters. *Note Case Tables::, for how to customize
600 which characters are upper or lower case and how to convert them.
602 - Command: capitalize-region START END
603 This function capitalizes all words in the region defined by START
604 and END. To capitalize means to convert each word's first
605 character to upper case and convert the rest of each word to lower
606 case. The function returns `nil'.
608 If one end of the region is in the middle of a word, the part of
609 the word within the region is treated as an entire word.
611 When `capitalize-region' is called interactively, START and END
612 are point and the mark, with the smallest first.
614 ---------- Buffer: foo ----------
615 This is the contents of the 5th foo.
616 ---------- Buffer: foo ----------
618 (capitalize-region 1 44)
621 ---------- Buffer: foo ----------
622 This Is The Contents Of The 5th Foo.
623 ---------- Buffer: foo ----------
625 - Command: downcase-region START END
626 This function converts all of the letters in the region defined by
627 START and END to lower case. The function returns `nil'.
629 When `downcase-region' is called interactively, START and END are
630 point and the mark, with the smallest first.
632 - Command: upcase-region START END
633 This function converts all of the letters in the region defined by
634 START and END to upper case. The function returns `nil'.
636 When `upcase-region' is called interactively, START and END are
637 point and the mark, with the smallest first.
639 - Command: capitalize-word COUNT
640 This function capitalizes COUNT words after point, moving point
641 over as it does. To capitalize means to convert each word's first
642 character to upper case and convert the rest of each word to lower
643 case. If COUNT is negative, the function capitalizes the -COUNT
644 previous words but does not move point. The value is `nil'.
646 If point is in the middle of a word, the part of the word before
647 point is ignored when moving forward. The rest is treated as an
650 When `capitalize-word' is called interactively, COUNT is set to
651 the numeric prefix argument.
653 - Command: downcase-word COUNT
654 This function converts the COUNT words after point to all lower
655 case, moving point over as it does. If COUNT is negative, it
656 converts the -COUNT previous words but does not move point. The
659 When `downcase-word' is called interactively, COUNT is set to the
660 numeric prefix argument.
662 - Command: upcase-word COUNT
663 This function converts the COUNT words after point to all upper
664 case, moving point over as it does. If COUNT is negative, it
665 converts the -COUNT previous words but does not move point. The
668 When `upcase-word' is called interactively, COUNT is set to the
669 numeric prefix argument.
672 File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
677 Text properties are an alternative interface to extents (*note
678 Extents::.), and are built on top of them. They are useful when you
679 want to view textual properties as being attached to the characters
680 themselves rather than to intervals of characters. The text property
681 interface is compatible with FSF Emacs.
683 Each character position in a buffer or a string can have a "text
684 property list", much like the property list of a symbol (*note Property
685 Lists::.). The properties belong to a particular character at a
686 particular place, such as, the letter `T' at the beginning of this
687 sentence or the first `o' in `foo'--if the same character occurs in two
688 different places, the two occurrences generally have different
691 Each property has a name and a value. Both of these can be any Lisp
692 object, but the name is normally a symbol. The usual way to access the
693 property list is to specify a name and ask what value corresponds to it.
695 Note that FSF Emacs also looks at the `category' property to find
696 defaults for text properties. We consider this too bogus to implement.
698 Copying text between strings and buffers preserves the properties
699 along with the characters; this includes such diverse functions as
700 `substring', `insert', and `buffer-substring'.
704 * Examining Properties:: Looking at the properties of one character.
705 * Changing Properties:: Setting the properties of a range of text.
706 * Property Search:: Searching for where a property changes value.
707 * Special Properties:: Particular properties with special meanings.
708 * Saving Properties:: Saving text properties in files, and reading
712 File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
714 Examining Text Properties
715 -------------------------
717 The simplest way to examine text properties is to ask for the value
718 of a particular property of a particular character. For that, use
719 `get-text-property'. Use `text-properties-at' to get the entire
720 property list of a character. *Note Property Search::, for functions
721 to examine the properties of a number of characters at once.
723 These functions handle both strings and buffers. (Keep in mind that
724 positions in a string start from 0, whereas positions in a buffer start
727 - Function: get-text-property POS PROP &optional OBJECT
728 This function returns the value of the PROP property of the
729 character after position POS in OBJECT (a buffer or string). The
730 argument OBJECT is optional and defaults to the current buffer.
732 - Function: get-char-property POS PROP &optional OBJECT
733 This function is like `get-text-property', except that it checks
734 all extents, not just text-property extents.
737 - Function: text-properties-at POSITION &optional OBJECT
738 This function returns the entire property list of the character at
739 POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
740 defaults to the current buffer.
742 - Variable: default-text-properties
743 This variable holds a property list giving default values for text
744 properties. Whenever a character does not specify a value for a
745 property, the value stored in this list is used instead. Here is
748 (setq default-text-properties '(foo 69))
749 ;; Make sure character 1 has no properties of its own.
750 (set-text-properties 1 2 nil)
751 ;; What we get, when we ask, is the default value.
752 (get-text-property 1 'foo)
756 File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
758 Changing Text Properties
759 ------------------------
761 The primitives for changing properties apply to a specified range of
762 text. The function `set-text-properties' (see end of section) sets the
763 entire property list of the text in that range; more often, it is
764 useful to add, change, or delete just certain properties specified by
767 Since text properties are considered part of the buffer's contents,
768 and can affect how the buffer looks on the screen, any change in the
769 text properties is considered a buffer modification. Buffer text
770 property changes are undoable (*note Undo::.).
772 - Function: put-text-property START END PROP VALUE &optional OBJECT
773 This function sets the PROP property to VALUE for the text between
774 START and END in the string or buffer OBJECT. If OBJECT is `nil',
775 it defaults to the current buffer.
777 - Function: add-text-properties START END PROPS &optional OBJECT
778 This function modifies the text properties for the text between
779 START and END in the string or buffer OBJECT. If OBJECT is `nil',
780 it defaults to the current buffer.
782 The argument PROPS specifies which properties to change. It
783 should have the form of a property list (*note Property Lists::.):
784 a list whose elements include the property names followed
785 alternately by the corresponding values.
787 The return value is `t' if the function actually changed some
788 property's value; `nil' otherwise (if PROPS is `nil' or its values
789 agree with those in the text).
791 For example, here is how to set the `comment' and `face'
792 properties of a range of text:
794 (add-text-properties START END
795 '(comment t face highlight))
797 - Function: remove-text-properties START END PROPS &optional OBJECT
798 This function deletes specified text properties from the text
799 between START and END in the string or buffer OBJECT. If OBJECT
800 is `nil', it defaults to the current buffer.
802 The argument PROPS specifies which properties to delete. It
803 should have the form of a property list (*note Property Lists::.):
804 a list whose elements are property names alternating with
805 corresponding values. But only the names matter--the values that
806 accompany them are ignored. For example, here's how to remove the
809 (remove-text-properties START END '(face nil))
811 The return value is `t' if the function actually changed some
812 property's value; `nil' otherwise (if PROPS is `nil' or if no
813 character in the specified text had any of those properties).
815 - Function: set-text-properties START END PROPS &optional OBJECT
816 This function completely replaces the text property list for the
817 text between START and END in the string or buffer OBJECT. If
818 OBJECT is `nil', it defaults to the current buffer.
820 The argument PROPS is the new property list. It should be a list
821 whose elements are property names alternating with corresponding
824 After `set-text-properties' returns, all the characters in the
825 specified range have identical properties.
827 If PROPS is `nil', the effect is to get rid of all properties from
828 the specified range of text. Here's an example:
830 (set-text-properties START END nil)
832 See also the function `buffer-substring-without-properties' (*note
833 Buffer Contents::.) which copies text from the buffer but does not copy
837 File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
839 Property Search Functions
840 -------------------------
842 In typical use of text properties, most of the time several or many
843 consecutive characters have the same value for a property. Rather than
844 writing your programs to examine characters one by one, it is much
845 faster to process chunks of text that have the same property value.
847 Here are functions you can use to do this. They use `eq' for
848 comparing property values. In all cases, OBJECT defaults to the
851 For high performance, it's very important to use the LIMIT argument
852 to these functions, especially the ones that search for a single
853 property--otherwise, they may spend a long time scanning to the end of
854 the buffer, if the property you are interested in does not change.
856 Remember that a position is always between two characters; the
857 position returned by these functions is between two characters with
858 different properties.
860 - Function: next-property-change POS &optional OBJECT LIMIT
861 The function scans the text forward from position POS in the
862 string or buffer OBJECT till it finds a change in some text
863 property, then returns the position of the change. In other
864 words, it returns the position of the first character beyond POS
865 whose properties are not identical to those of the character just
868 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
869 there is no property change before that point,
870 `next-property-change' returns LIMIT.
872 The value is `nil' if the properties remain unchanged all the way
873 to the end of OBJECT and LIMIT is `nil'. If the value is
874 non-`nil', it is a position greater than or equal to POS. The
875 value equals POS only when LIMIT equals POS.
877 Here is an example of how to scan the buffer by chunks of text
878 within which all properties are constant:
881 (let ((plist (text-properties-at (point)))
883 (or (next-property-change (point) (current-buffer))
885 Process text from point to NEXT-CHANGE...
886 (goto-char next-change)))
888 - Function: next-single-property-change POS PROP &optional OBJECT LIMIT
889 The function scans the text forward from position POS in the
890 string or buffer OBJECT till it finds a change in the PROP
891 property, then returns the position of the change. In other
892 words, it returns the position of the first character beyond POS
893 whose PROP property differs from that of the character just after
896 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
897 there is no property change before that point,
898 `next-single-property-change' returns LIMIT.
900 The value is `nil' if the property remains unchanged all the way to
901 the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
902 it is a position greater than or equal to POS; it equals POS only
905 - Function: previous-property-change POS &optional OBJECT LIMIT
906 This is like `next-property-change', but scans back from POS
907 instead of forward. If the value is non-`nil', it is a position
908 less than or equal to POS; it equals POS only if LIMIT equals POS.
910 - Function: previous-single-property-change POS PROP &optional OBJECT
912 This is like `next-single-property-change', but scans back from
913 POS instead of forward. If the value is non-`nil', it is a
914 position less than or equal to POS; it equals POS only if LIMIT
917 - Function: text-property-any START END PROP VALUE &optional OBJECT
918 This function returns non-`nil' if at least one character between
919 START and END has a property PROP whose value is VALUE. More
920 precisely, it returns the position of the first such character.
921 Otherwise, it returns `nil'.
923 The optional fifth argument, OBJECT, specifies the string or
924 buffer to scan. Positions are relative to OBJECT. The default
925 for OBJECT is the current buffer.
927 - Function: text-property-not-all START END PROP VALUE &optional OBJECT
928 This function returns non-`nil' if at least one character between
929 START and END has a property PROP whose value differs from VALUE.
930 More precisely, it returns the position of the first such
931 character. Otherwise, it returns `nil'.
933 The optional fifth argument, OBJECT, specifies the string or
934 buffer to scan. Positions are relative to OBJECT. The default
935 for OBJECT is the current buffer.
938 File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
940 Properties with Special Meanings
941 --------------------------------
943 The predefined properties are the same as those for extents. *Note
947 File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
949 Saving Text Properties in Files
950 -------------------------------
952 You can save text properties in files, and restore text properties
953 when inserting the files, using these two hooks:
955 - Variable: write-region-annotate-functions
956 This variable's value is a list of functions for `write-region' to
957 run to encode text properties in some fashion as annotations to
958 the text being written in the file. *Note Writing to Files::.
960 Each function in the list is called with two arguments: the start
961 and end of the region to be written. These functions should not
962 alter the contents of the buffer. Instead, they should return
963 lists indicating annotations to write in the file in addition to
964 the text in the buffer.
966 Each function should return a list of elements of the form
967 `(POSITION . STRING)', where POSITION is an integer specifying the
968 relative position in the text to be written, and STRING is the
969 annotation to add there.
971 Each list returned by one of these functions must be already
972 sorted in increasing order by POSITION. If there is more than one
973 function, `write-region' merges the lists destructively into one
976 When `write-region' actually writes the text from the buffer to the
977 file, it intermixes the specified annotations at the corresponding
978 positions. All this takes place without modifying the buffer.
980 - Variable: after-insert-file-functions
981 This variable holds a list of functions for `insert-file-contents'
982 to call after inserting a file's contents. These functions should
983 scan the inserted text for annotations, and convert them to the
984 text properties they stand for.
986 Each function receives one argument, the length of the inserted
987 text; point indicates the start of that text. The function should
988 scan that text for annotations, delete them, and create the text
989 properties that the annotations specify. The function should
990 return the updated length of the inserted text, as it stands after
991 those changes. The value returned by one function becomes the
992 argument to the next function.
994 These functions should always return with point at the beginning of
997 The intended use of `after-insert-file-functions' is for converting
998 some sort of textual annotations into actual text properties. But
999 other uses may be possible.
1001 We invite users to write Lisp programs to store and retrieve text
1002 properties in files, using these hooks, and thus to experiment with
1003 various data formats and find good ones. Eventually we hope users will
1004 produce good, general extensions we can install in Emacs.
1006 We suggest not trying to handle arbitrary Lisp objects as property
1007 names or property values--because a program that general is probably
1008 difficult to write, and slow. Instead, choose a set of possible data
1009 types that are reasonably flexible, and not too hard to encode.
1011 *Note Format Conversion::, for a related feature.
1014 File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
1016 Substituting for a Character Code
1017 =================================
1019 The following functions replace characters within a specified region
1020 based on their character codes.
1022 - Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional
1024 This function replaces all occurrences of the character OLD-CHAR
1025 with the character NEW-CHAR in the region of the current buffer
1026 defined by START and END.
1028 If NOUNDO is non-`nil', then `subst-char-in-region' does not
1029 record the change for undo and does not mark the buffer as
1030 modified. This feature is used for controlling selective display
1031 (*note Selective Display::.).
1033 `subst-char-in-region' does not move point and returns `nil'.
1035 ---------- Buffer: foo ----------
1036 This is the contents of the buffer before.
1037 ---------- Buffer: foo ----------
1039 (subst-char-in-region 1 20 ?i ?X)
1042 ---------- Buffer: foo ----------
1043 ThXs Xs the contents of the buffer before.
1044 ---------- Buffer: foo ----------
1046 - Function: translate-region START END TABLE
1047 This function applies a translation table to the characters in the
1048 buffer between positions START and END. The translation table
1049 TABLE can be either a string, a vector, or a char-table.
1051 If TABLE is a string, its Nth element is the mapping for the
1052 character with code N.
1054 If TABLE is a vector, its Nth element is the mapping for character
1055 with code N. Legal mappings are characters, strings, or `nil'
1056 (meaning don't replace.)
1058 If TABLE is a char-table, its elements describe the mapping
1059 between characters and their replacements. The char-table should
1060 be of type `char' or `generic'.
1062 When the TABLE is a string or vector and its length is less than
1063 the total number of characters (256 without Mule), any characters
1064 with codes larger than the length of TABLE are not altered by the
1067 The return value of `translate-region' is the number of characters
1068 that were actually changed by the translation. This does not
1069 count characters that were mapped into themselves in the
1072 *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
1073 to be a string. This is still the case in FSF Emacs.
1075 The following example creates a char-table that is passed to
1076 `translate-region', which translates character `a' to `the letter
1077 a', removes character `b', and translates character `c' to newline.
1079 ---------- Buffer: foo ----------
1080 Here is a sentence in the buffer.
1081 ---------- Buffer: foo ----------
1083 (let ((table (make-char-table 'generic)))
1084 (put-char-table ?a "the letter a" table)
1085 (put-char-table ?b "" table)
1086 (put-char-table ?c ?\n table)
1087 (translate-region (point-min) (point-max) table))
1090 ---------- Buffer: foo ----------
1091 Here is the letter a senten
1093 ---------- Buffer: foo ----------
1096 File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
1101 A register is a sort of variable used in XEmacs editing that can
1102 hold a marker, a string, a rectangle, a window configuration (of one
1103 frame), or a frame configuration (of all frames). Each register is
1104 named by a single character. All characters, including control and
1105 meta characters (but with the exception of `C-g'), can be used to name
1106 registers. Thus, there are 255 possible registers. A register is
1107 designated in Emacs Lisp by a character that is its name.
1109 The functions in this section return unpredictable values unless
1112 - Variable: register-alist
1113 This variable is an alist of elements of the form `(NAME .
1114 CONTENTS)'. Normally, there is one element for each XEmacs
1115 register that has been used.
1117 The object NAME is a character (an integer) identifying the
1118 register. The object CONTENTS is a string, marker, or list
1119 representing the register contents. A string represents text
1120 stored in the register. A marker represents a position. A list
1121 represents a rectangle; its elements are strings, one per line of
1124 - Function: get-register REG
1125 This function returns the contents of the register REG, or `nil'
1126 if it has no contents.
1128 - Function: set-register REG VALUE
1129 This function sets the contents of register REG to VALUE. A
1130 register can be set to any value, but the other register functions
1131 expect only certain data types. The return value is VALUE.
1133 - Command: view-register REG
1134 This command displays what is contained in register REG.
1136 - Command: insert-register REG &optional BEFOREP
1137 This command inserts contents of register REG into the current
1140 Normally, this command puts point before the inserted text, and the
1141 mark after it. However, if the optional second argument BEFOREP
1142 is non-`nil', it puts the mark before and point after. You can
1143 pass a non-`nil' second argument BEFOREP to this function
1144 interactively by supplying any prefix argument.
1146 If the register contains a rectangle, then the rectangle is
1147 inserted with its upper left corner at point. This means that
1148 text is inserted in the current line and underneath it on
1151 If the register contains something other than saved text (a
1152 string) or a rectangle (a list), currently useless things happen.
1153 This may be changed in the future.
1156 File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
1158 Transposition of Text
1159 =====================
1161 This subroutine is used by the transposition commands.
1163 - Function: transpose-regions START1 END1 START2 END2 &optional
1165 This function exchanges two nonoverlapping portions of the buffer.
1166 Arguments START1 and END1 specify the bounds of one portion and
1167 arguments START2 and END2 specify the bounds of the other portion.
1169 Normally, `transpose-regions' relocates markers with the transposed
1170 text; a marker previously positioned within one of the two
1171 transposed portions moves along with that portion, thus remaining
1172 between the same two characters in their new position. However,
1173 if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
1174 this--it leaves all markers unrelocated.
projects / chise / xemacs-chise.git.1 / blob