1 This is ../info/lispref.info, produced by makeinfo version 4.6 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: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
55 Maintaining Undo Lists
56 ======================
58 This section describes how to enable and disable undo information for a
59 given buffer. It also explains how the undo list is truncated
60 automatically so it doesn't get too big.
62 Recording of undo information in a newly created buffer is normally
63 enabled to start with; but if the buffer name starts with a space, the
64 undo recording is initially disabled. You can explicitly enable or
65 disable undo recording with the following two functions, or by setting
66 `buffer-undo-list' yourself.
68 - Command: buffer-enable-undo &optional buffer-or-name
69 This command enables recording undo information for buffer
70 BUFFER-OR-NAME, so that subsequent changes can be undone. If no
71 argument is supplied, then the current buffer is used. This
72 function does nothing if undo recording is already enabled in the
73 buffer. It returns `nil'.
75 In an interactive call, BUFFER-OR-NAME is the current buffer. You
76 cannot specify any other buffer.
78 - Command: buffer-disable-undo &optional buffer
79 - Command: buffer-flush-undo &optional buffer
80 This function discards the undo list of BUFFER, and disables
81 further recording of undo information. As a result, it is no
82 longer possible to undo either previous changes or any subsequent
83 changes. If the undo list of BUFFER is already disabled, this
84 function has no effect.
86 This function returns `nil'. It cannot be called interactively.
88 The name `buffer-flush-undo' is not considered obsolete, but the
89 preferred name `buffer-disable-undo' is new as of Emacs versions
92 As editing continues, undo lists get longer and longer. To prevent
93 them from using up all available memory space, garbage collection trims
94 them back to size limits you can set. (For this purpose, the "size" of
95 an undo list measures the cons cells that make up the list, plus the
96 strings of deleted text.) Two variables control the range of acceptable
97 sizes: `undo-limit' and `undo-strong-limit'.
99 - Variable: undo-limit
100 This is the soft limit for the acceptable size of an undo list.
101 The change group at which this size is exceeded is the last one
104 - Variable: undo-strong-limit
105 This is the upper limit for the acceptable size of an undo list.
106 The change group at which this size is exceeded is discarded
107 itself (along with all older change groups). There is one
108 exception: the very latest change group is never discarded no
109 matter how big it is.
112 File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
117 "Filling" means adjusting the lengths of lines (by moving the line
118 breaks) so that they are nearly (but no greater than) a specified
119 maximum width. Additionally, lines can be "justified", which means
120 inserting spaces to make the left and/or right margins line up
121 precisely. The width is controlled by the variable `fill-column'. For
122 ease of reading, lines should be no longer than 70 or so columns.
124 You can use Auto Fill mode (*note Auto Filling::) to fill text
125 automatically as you insert it, but changes to existing text may leave
126 it improperly filled. Then you must fill the text explicitly.
128 Most of the commands in this section return values that are not
129 meaningful. All the functions that do filling take note of the current
130 left margin, current right margin, and current justification style
131 (*note Margins::). If the current justification style is `none', the
132 filling functions don't actually do anything.
134 Several of the filling functions have an argument JUSTIFY. If it is
135 non-`nil', that requests some kind of justification. It can be `left',
136 `right', `full', or `center', to request a specific style of
137 justification. If it is `t', that means to use the current
138 justification style for this part of the text (see
139 `current-justification', below).
141 When you call the filling functions interactively, using a prefix
142 argument implies the value `full' for JUSTIFY.
144 - Command: fill-paragraph justify
145 This command fills the paragraph at or after point. If JUSTIFY is
146 non-`nil', each line is justified as well. It uses the ordinary
147 paragraph motion commands to find paragraph boundaries. *Note
148 Paragraphs: (xemacs)Paragraphs.
150 - Command: fill-region start end &optional justify
151 This command fills each of the paragraphs in the region from START
152 to END. It justifies as well if JUSTIFY is non-`nil'.
154 The variable `paragraph-separate' controls how to distinguish
155 paragraphs. *Note Standard Regexps::.
157 - Command: fill-individual-paragraphs start end &optional justify
159 This command fills each paragraph in the region according to its
160 individual fill prefix. Thus, if the lines of a paragraph were
161 indented with spaces, the filled paragraph will remain indented in
164 The first two arguments, START and END, are the beginning and end
165 of the region to be filled. The third and fourth arguments,
166 JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
167 paragraphs are justified as well as filled. If MAIL-FLAG is
168 non-`nil', it means the function is operating on a mail message
169 and therefore should not fill the header lines.
171 Ordinarily, `fill-individual-paragraphs' regards each change in
172 indentation as starting a new paragraph. If
173 `fill-individual-varying-indent' is non-`nil', then only separator
174 lines separate paragraphs. That mode can handle indented
175 paragraphs with additional indentation on the first line.
177 - User Option: fill-individual-varying-indent
178 This variable alters the action of `fill-individual-paragraphs' as
181 - Command: fill-region-as-paragraph start end &optional justify
182 This command considers a region of text as a paragraph and fills
183 it. If the region was made up of many paragraphs, the blank lines
184 between paragraphs are removed. This function justifies as well
185 as filling when JUSTIFY is non-`nil'.
187 In an interactive call, any prefix argument requests justification.
189 In Adaptive Fill mode, which is enabled by default,
190 `fill-region-as-paragraph' on an indented paragraph when there is
191 no fill prefix uses the indentation of the second line of the
192 paragraph as the fill prefix.
194 - Command: justify-current-line how eop nosqueeze
195 This command inserts spaces between the words of the current line
196 so that the line ends exactly at `fill-column'. It returns `nil'.
198 The argument HOW, if non-`nil' specifies explicitly the style of
199 justification. It can be `left', `right', `full', `center', or
200 `none'. If it is `t', that means to do follow specified
201 justification style (see `current-justification', below). `nil'
202 means to do full justification.
204 If EOP is non-`nil', that means do left-justification when
205 `current-justification' specifies full justification. This is used
206 for the last line of a paragraph; even if the paragraph as a whole
207 is fully justified, the last line should not be.
209 If NOSQUEEZE is non-`nil', that means do not change interior
212 - User Option: default-justification
213 This variable's value specifies the style of justification to use
214 for text that doesn't specify a style with a text property. The
215 possible values are `left', `right', `full', `center', or `none'.
216 The default value is `left'.
218 - Function: current-justification
219 This function returns the proper justification style to use for
220 filling the text around point.
222 - Variable: fill-paragraph-function
223 This variable provides a way for major modes to override the
224 filling of paragraphs. If the value is non-`nil',
225 `fill-paragraph' calls this function to do the work. If the
226 function returns a non-`nil' value, `fill-paragraph' assumes the
227 job is done, and immediately returns that value.
229 The usual use of this feature is to fill comments in programming
230 language modes. If the function needs to fill a paragraph in the
231 usual way, it can do so as follows:
233 (let ((fill-paragraph-function nil))
234 (fill-paragraph arg))
236 - Variable: use-hard-newlines
237 If this variable is non-`nil', the filling functions do not delete
238 newlines that have the `hard' text property. These "hard
239 newlines" act as paragraph separators.
242 File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
247 - User Option: fill-prefix
248 This variable specifies a string of text that appears at the
249 beginning of normal text lines and should be disregarded when
250 filling them. Any line that fails to start with the fill prefix
251 is considered the start of a paragraph; so is any line that starts
252 with the fill prefix followed by additional whitespace. Lines
253 that start with the fill prefix but no additional whitespace are
254 ordinary text lines that can be filled together. The resulting
255 filled lines also start with the fill prefix.
257 The fill prefix follows the left margin whitespace, if any.
259 - User Option: fill-column
260 This buffer-local variable specifies the maximum width of filled
261 lines. Its value should be an integer, which is a number of
262 columns. All the filling, justification and centering commands
263 are affected by this variable, including Auto Fill mode (*note
266 As a practical matter, if you are writing text for other people to
267 read, you should set `fill-column' to no more than 70. Otherwise
268 the line will be too long for people to read comfortably, and this
269 can make the text seem clumsy.
271 - Variable: default-fill-column
272 The value of this variable is the default value for `fill-column'
273 in buffers that do not override it. This is the same as
274 `(default-value 'fill-column)'.
276 The default value for `default-fill-column' is 70.
278 - Command: set-left-margin from to margin
279 This sets the `left-margin' property on the text from FROM to TO
280 to the value MARGIN. If Auto Fill mode is enabled, this command
281 also refills the region to fit the new margin.
283 - Command: set-right-margin from to margin
284 This sets the `right-margin' property on the text from FROM to TO
285 to the value MARGIN. If Auto Fill mode is enabled, this command
286 also refills the region to fit the new margin.
288 - Function: current-left-margin
289 This function returns the proper left margin value to use for
290 filling the text around point. The value is the sum of the
291 `left-margin' property of the character at the start of the
292 current line (or zero if none), and the value of the variable
295 - Function: current-fill-column
296 This function returns the proper fill column value to use for
297 filling the text around point. The value is the value of the
298 `fill-column' variable, minus the value of the `right-margin'
299 property of the character after point.
301 - Command: move-to-left-margin &optional n force
302 This function moves point to the left margin of the current line.
303 The column moved to is determined by calling the function
304 `current-left-margin'. If the argument N is non-`nil',
305 `move-to-left-margin' moves forward N-1 lines first.
307 If FORCE is non-`nil', that says to fix the line's indentation if
308 that doesn't match the left margin value.
310 - Function: delete-to-left-margin &optional from to
311 This function removes left margin indentation from the text
312 between FROM and TO. The amount of indentation to delete is
313 determined by calling `current-left-margin'. In no case does this
314 function delete non-whitespace.
316 The arguments FROM and TO are optional; the default is the whole
319 - Function: indent-to-left-margin
320 This is the default `indent-line-function', used in Fundamental
321 mode, Text mode, etc. Its effect is to adjust the indentation at
322 the beginning of the current line to the value specified by the
323 variable `left-margin'. This may involve either inserting or
326 - Variable: left-margin
327 This variable specifies the base left margin column. In
328 Fundamental mode, <LFD> indents to this column. This variable
329 automatically becomes buffer-local when set in any fashion.
332 File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
337 Auto Fill mode is a minor mode that fills lines automatically as text
338 is inserted. This section describes the hook used by Auto Fill mode.
339 For a description of functions that you can call explicitly to fill and
340 justify existing text, see *Note Filling::.
342 Auto Fill mode also enables the functions that change the margins and
343 justification style to refill portions of the text. *Note Margins::.
345 - Variable: auto-fill-function
346 The value of this variable should be a function (of no arguments)
347 to be called after self-inserting a space or a newline. It may be
348 `nil', in which case nothing special is done in that case.
350 The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
351 mode is enabled. That is a function whose sole purpose is to
352 implement the usual strategy for breaking a line.
354 In older Emacs versions, this variable was named
355 `auto-fill-hook', but since it is not called with the
356 standard convention for hooks, it was renamed to
357 `auto-fill-function' in version 19.
360 File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
365 The sorting functions described in this section all rearrange text in a
366 buffer. This is in contrast to the function `sort', which rearranges
367 the order of the elements of a list (*note Rearrangement::). The
368 values returned by these functions are not meaningful.
370 - Function: sort-subr reverse nextrecfun endrecfun &optional
371 startkeyfun endkeyfun
372 This function is the general text-sorting routine that divides a
373 buffer into records and sorts them. Most of the commands in this
374 section use this function.
376 To understand how `sort-subr' works, consider the whole accessible
377 portion of the buffer as being divided into disjoint pieces called
378 "sort records". The records may or may not be contiguous; they may
379 not overlap. A portion of each sort record (perhaps all of it) is
380 designated as the sort key. Sorting rearranges the records in
381 order by their sort keys.
383 Usually, the records are rearranged in order of ascending sort key.
384 If the first argument to the `sort-subr' function, REVERSE, is
385 non-`nil', the sort records are rearranged in order of descending
388 The next four arguments to `sort-subr' are functions that are
389 called to move point across a sort record. They are called many
390 times from within `sort-subr'.
392 1. NEXTRECFUN is called with point at the end of a record. This
393 function moves point to the start of the next record. The
394 first record is assumed to start at the position of point
395 when `sort-subr' is called. Therefore, you should usually
396 move point to the beginning of the buffer before calling
399 This function can indicate there are no more sort records by
400 leaving point at the end of the buffer.
402 2. ENDRECFUN is called with point within a record. It moves
403 point to the end of the record.
405 3. STARTKEYFUN is called to move point from the start of a
406 record to the start of the sort key. This argument is
407 optional; if it is omitted, the whole record is the sort key.
408 If supplied, the function should either return a non-`nil'
409 value to be used as the sort key, or return `nil' to indicate
410 that the sort key is in the buffer starting at point. In the
411 latter case, ENDKEYFUN is called to find the end of the sort
414 4. ENDKEYFUN is called to move point from the start of the sort
415 key to the end of the sort key. This argument is optional.
416 If STARTKEYFUN returns `nil' and this argument is omitted (or
417 `nil'), then the sort key extends to the end of the record.
418 There is no need for ENDKEYFUN if STARTKEYFUN returns a
421 As an example of `sort-subr', here is the complete function
422 definition for `sort-lines':
424 ;; Note that the first two lines of doc string
425 ;; are effectively one line when viewed by a user.
426 (defun sort-lines (reverse start end)
427 "Sort lines in region alphabetically.
428 Called from a program, there are three arguments:
429 REVERSE (non-nil means reverse order),
430 and START and END (the region to sort)."
433 (narrow-to-region start end)
434 (goto-char (point-min))
439 Here `forward-line' moves point to the start of the next record,
440 and `end-of-line' moves point to the end of record. We do not pass
441 the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
442 is used as the sort key.
444 The `sort-paragraphs' function is very much the same, except that
445 its `sort-subr' call looks like this:
450 (skip-chars-forward "\n \t\f")))
453 - Command: sort-regexp-fields reverse record-regexp key-regexp start
455 This command sorts the region between START and END alphabetically
456 as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
457 negative integer, then sorting is in reverse order.
459 Alphabetical sorting means that two sort keys are compared by
460 comparing the first characters of each, the second characters of
461 each, and so on. If a mismatch is found, it means that the sort
462 keys are unequal; the sort key whose character is less at the
463 point of first mismatch is the lesser sort key. The individual
464 characters are compared according to their numerical values.
465 Since Emacs uses the ASCII character set, the ordering in that set
466 determines alphabetical order.
468 The value of the RECORD-REGEXP argument specifies how to divide
469 the buffer into sort records. At the end of each record, a search
470 is done for this regular expression, and the text that matches it
471 is the next record. For example, the regular expression `^.+$',
472 which matches lines with at least one character besides a newline,
473 would make each such line into a sort record. *Note Regular
474 Expressions::, for a description of the syntax and meaning of
477 The value of the KEY-REGEXP argument specifies what part of each
478 record is the sort key. The KEY-REGEXP could match the whole
479 record, or only a part. In the latter case, the rest of the
480 record has no effect on the sorted order of records, but it is
481 carried along when the record moves to its new position.
483 The KEY-REGEXP argument can refer to the text matched by a
484 subexpression of RECORD-REGEXP, or it can be a regular expression
490 then the text matched by the DIGITth `\(...\)' parenthesis
491 grouping in RECORD-REGEXP is the sort key.
494 then the whole record is the sort key.
497 then `sort-regexp-fields' searches for a match for the regular
498 expression within the record. If such a match is found, it
499 is the sort key. If there is no match for KEY-REGEXP within
500 a record then that record is ignored, which means its
501 position in the buffer is not changed. (The other records
504 For example, if you plan to sort all the lines in the region by the
505 first word on each line starting with the letter `f', you should
506 set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'. The
507 resulting expression looks like this:
509 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
513 If you call `sort-regexp-fields' interactively, it prompts for
514 RECORD-REGEXP and KEY-REGEXP in the minibuffer.
516 - Command: sort-lines reverse start end
517 This command alphabetically sorts lines in the region between
518 START and END. If REVERSE is non-`nil', the sort is in reverse
521 - Command: sort-paragraphs reverse start end
522 This command alphabetically sorts paragraphs in the region between
523 START and END. If REVERSE is non-`nil', the sort is in reverse
526 - Command: sort-pages reverse start end
527 This command alphabetically sorts pages in the region between
528 START and END. If REVERSE is non-`nil', the sort is in reverse
531 - Command: sort-fields field start end
532 This command sorts lines in the region between START and END,
533 comparing them alphabetically by the FIELDth field of each line.
534 Fields are separated by whitespace and numbered starting from 1.
535 If FIELD is negative, sorting is by the -FIELDth field from the
536 end of the line. This command is useful for sorting tables.
538 - Command: sort-numeric-fields field start end
539 This command sorts lines in the region between START and END,
540 comparing them numerically by the FIELDth field of each line. The
541 specified field must contain a number in each line of the region.
542 Fields are separated by whitespace and numbered starting from 1.
543 If FIELD is negative, sorting is by the -FIELDth field from the
544 end of the line. This command is useful for sorting tables.
546 - Command: sort-columns reverse &optional start end
547 This command sorts the lines in the region between START and END,
548 comparing them alphabetically by a certain range of columns. The
549 column positions of START and END bound the range of columns to
552 If REVERSE is non-`nil', the sort is in reverse order.
554 One unusual thing about this command is that the entire line
555 containing position START, and the entire line containing position
556 END, are included in the region sorted.
558 Note that `sort-columns' uses the `sort' utility program, and so
559 cannot work properly on text containing tab characters. Use `M-x
560 `untabify'' to convert tabs to spaces before sorting.
563 File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
568 The column functions convert between a character position (counting
569 characters from the beginning of the buffer) and a column position
570 (counting screen characters from the beginning of a line).
572 A character counts according to the number of columns it occupies on
573 the screen. This means control characters count as occupying 2 or 4
574 columns, depending upon the value of `ctl-arrow', and tabs count as
575 occupying a number of columns that depends on the value of `tab-width'
576 and on the column where the tab begins. *Note Usual Display::.
578 Column number computations ignore the width of the window and the
579 amount of horizontal scrolling. Consequently, a column value can be
580 arbitrarily high. The first (or leftmost) column is numbered 0.
582 - Function: current-column &optional buffer
583 This function returns the horizontal position of point, measured in
584 columns, counting from 0 at the left margin.
586 This is calculated by adding together the widths of all the
587 displayed representations of the character between the start of
588 the previous line and point. (e.g. control characters will have a
589 width of 2 or 4, tabs will have a variable width.)
591 Ignores the finite width of frame displaying the buffer, which
592 means that this function may return values greater than
595 Whether the line is visible (if `selective-display' is t) has no
596 effect; however, ^M is treated as end of line when
597 `selective-display' is t.
599 If BUFFER is nil, the current buffer is assumed.
601 For an example of using `current-column', see the description of
602 `count-lines' in *Note Text Lines::.
604 - Function: move-to-column column &optional force buffer
605 This function moves point to COLUMN in the current line. The
606 calculation of COLUMN takes into account the widths of the
607 displayed representations of the characters between the start of
610 If column COLUMN is beyond the end of the line, point moves to the
611 end of the line. If COLUMN is negative, point moves to the
612 beginning of the line.
614 If it is impossible to move to column COLUMN because that is in
615 the middle of a multicolumn character such as a tab, point moves
616 to the end of that character. However, if FORCE is non-`nil', and
617 COLUMN is in the middle of a tab, then `move-to-column' converts
618 the tab into spaces so that it can move precisely to column
619 COLUMN. Other multicolumn characters can cause anomalies despite
620 FORCE, since there is no way to split them.
622 The argument FORCE also has an effect if the line isn't long
623 enough to reach column COLUMN; in that case, unless the value of
624 FORCE is the special value `coerce', it says to add whitespace at
625 the end of the line to reach that column.
627 If COLUMN is not a non-negative integer, an error is signaled.
629 The return value is the column number actually moved to.
632 File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
637 The indentation functions are used to examine, move to, and change
638 whitespace that is at the beginning of a line. Some of the functions
639 can also change whitespace elsewhere on a line. Columns and indentation
640 count from zero at the left margin.
644 * Primitive Indent:: Functions used to count and insert indentation.
645 * Mode-Specific Indent:: Customize indentation for different modes.
646 * Region Indent:: Indent all the lines in a region.
647 * Relative Indent:: Indent the current line based on previous lines.
648 * Indent Tabs:: Adjustable, typewriter-like tab stops.
649 * Motion by Indent:: Move to first non-blank character.
652 File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
654 Indentation Primitives
655 ----------------------
657 This section describes the primitive functions used to count and insert
658 indentation. The functions in the following sections use these
661 - Function: current-indentation &optional buffer
662 This function returns the indentation of the current line, which is
663 the horizontal position of the first nonblank character. If the
664 contents are entirely blank, then this is the horizontal position
665 of the end of the line.
667 - Command: indent-to column &optional minimum buffer
668 This function indents from point with tabs and spaces until COLUMN
669 is reached. If MINIMUM is specified and non-`nil', then at least
670 that many spaces are inserted even if this requires going beyond
671 COLUMN. Otherwise the function does nothing if point is already
672 beyond COLUMN. The value is the column at which the inserted
673 indentation ends. If BUFFER is `nil', the current buffer is
676 - User Option: indent-tabs-mode
677 If this variable is non-`nil', indentation functions can insert
678 tabs as well as spaces. Otherwise, they insert only spaces.
679 Setting this variable automatically makes it local to the current
683 File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
685 Indentation Controlled by Major Mode
686 ------------------------------------
688 An important function of each major mode is to customize the <TAB> key
689 to indent properly for the language being edited. This section
690 describes the mechanism of the <TAB> key and how to control it. The
691 functions in this section return unpredictable values.
693 - Variable: indent-line-function
694 This variable's value is the function to be used by <TAB> (and
695 various commands) to indent the current line. The command
696 `indent-according-to-mode' does no more than call this function.
698 In Lisp mode, the value is the symbol `lisp-indent-line'; in C
699 mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
700 Fundamental mode, Text mode, and many other modes with no standard
701 for indentation, the value is `indent-to-left-margin' (which is the
704 - Command: indent-according-to-mode
705 This command calls the function in `indent-line-function' to
706 indent the current line in a way appropriate for the current major
709 - Command: indent-for-tab-command &optional prefix-arg
710 This command calls the function in `indent-line-function' to indent
711 the current line; except that if that function is
712 `indent-to-left-margin', it calls `insert-tab' instead. (That is
713 a trivial command that inserts a tab character.)
715 - Command: newline-and-indent
716 This function inserts a newline, then indents the new line (the one
717 following the newline just inserted) according to the major mode.
719 It does indentation by calling the current `indent-line-function'.
720 In programming language modes, this is the same thing <TAB> does,
721 but in some text modes, where <TAB> inserts a tab,
722 `newline-and-indent' indents to the column specified by
725 - Command: reindent-then-newline-and-indent
726 This command reindents the current line, inserts a newline at
727 point, and then reindents the new line (the one following the
728 newline just inserted).
730 This command does indentation on both lines according to the
731 current major mode, by calling the current value of
732 `indent-line-function'. In programming language modes, this is
733 the same thing <TAB> does, but in some text modes, where <TAB>
734 inserts a tab, `reindent-then-newline-and-indent' indents to the
735 column specified by `left-margin'.
738 File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
740 Indenting an Entire Region
741 --------------------------
743 This section describes commands that indent all the lines in the
744 region. They return unpredictable values.
746 - Command: indent-region start end to-column
747 This command indents each nonblank line starting between START
748 (inclusive) and END (exclusive). If TO-COLUMN is `nil',
749 `indent-region' indents each nonblank line by calling the current
750 mode's indentation function, the value of `indent-line-function'.
752 If TO-COLUMN is non-`nil', it should be an integer specifying the
753 number of columns of indentation; then this function gives each
754 line exactly that much indentation, by either adding or deleting
757 If there is a fill prefix, `indent-region' indents each line by
758 making it start with the fill prefix.
760 - Variable: indent-region-function
761 The value of this variable is a function that can be used by
762 `indent-region' as a short cut. You should design the function so
763 that it will produce the same results as indenting the lines of the
764 region one by one, but presumably faster.
766 If the value is `nil', there is no short cut, and `indent-region'
767 actually works line by line.
769 A short-cut function is useful in modes such as C mode and Lisp
770 mode, where the `indent-line-function' must scan from the
771 beginning of the function definition: applying it to each line
772 would be quadratic in time. The short cut can update the scan
773 information as it moves through the lines indenting them; this
774 takes linear time. In a mode where indenting a line individually
775 is fast, there is no need for a short cut.
777 `indent-region' with a non-`nil' argument TO-COLUMN has a
778 different meaning and does not use this variable.
780 - Command: indent-rigidly start end count
781 This command indents all lines starting between START (inclusive)
782 and END (exclusive) sideways by COUNT columns. This "preserves
783 the shape" of the affected region, moving it as a rigid unit.
784 Consequently, this command is useful not only for indenting
785 regions of unindented text, but also for indenting regions of
788 For example, if COUNT is 3, this command adds 3 columns of
789 indentation to each of the lines beginning in the region specified.
791 In Mail mode, `C-c C-y' (`mail-yank-original') uses
792 `indent-rigidly' to indent the text copied from the message being
795 - Command: indent-code-rigidly start end columns &optional
797 This is like `indent-rigidly', except that it doesn't alter lines
798 that start within strings or comments.
800 In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
801 the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
804 File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
806 Indentation Relative to Previous Lines
807 --------------------------------------
809 This section describes two commands that indent the current line based
810 on the contents of previous lines.
812 - Command: indent-relative &optional unindented-ok
813 This command inserts whitespace at point, extending to the same
814 column as the next "indent point" of the previous nonblank line.
815 An indent point is a non-whitespace character following
816 whitespace. The next indent point is the first one at a column
817 greater than the current column of point. For example, if point
818 is underneath and to the left of the first non-blank character of
819 a line of text, it moves to that column by inserting whitespace.
821 If the previous nonblank line has no next indent point (i.e., none
822 at a great enough column position), `indent-relative' either does
823 nothing (if UNINDENTED-OK is non-`nil') or calls
824 `tab-to-tab-stop'. Thus, if point is underneath and to the right
825 of the last column of a short line of text, this command ordinarily
826 moves point to the next tab stop by inserting whitespace.
828 The return value of `indent-relative' is unpredictable.
830 In the following example, point is at the beginning of the second
833 This line is indented twelve spaces.
834 -!-The quick brown fox jumped.
836 Evaluation of the expression `(indent-relative nil)' produces the
839 This line is indented twelve spaces.
840 -!-The quick brown fox jumped.
842 In this example, point is between the `m' and `p' of `jumped':
844 This line is indented twelve spaces.
845 The quick brown fox jum-!-ped.
847 Evaluation of the expression `(indent-relative nil)' produces the
850 This line is indented twelve spaces.
851 The quick brown fox jum -!-ped.
853 - Command: indent-relative-maybe
854 This command indents the current line like the previous nonblank
855 line. It calls `indent-relative' with `t' as the UNINDENTED-OK
856 argument. The return value is unpredictable.
858 If the previous nonblank line has no indent points beyond the
859 current column, this command does nothing.
862 File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
864 Adjustable "Tab Stops"
865 ----------------------
867 This section explains the mechanism for user-specified "tab stops" and
868 the mechanisms that use and set them. The name "tab stops" is used
869 because the feature is similar to that of the tab stops on a
870 typewriter. The feature works by inserting an appropriate number of
871 spaces and tab characters to reach the next tab stop column; it does not
872 affect the display of tab characters in the buffer (*note Usual
873 Display::). Note that the <TAB> character as input uses this tab stop
874 feature only in a few major modes, such as Text mode.
876 - Command: tab-to-tab-stop
877 This command inserts spaces or tabs up to the next tab stop column
878 defined by `tab-stop-list'. It searches the list for an element
879 greater than the current column number, and uses that element as
880 the column to indent to. It does nothing if no such element is
883 - User Option: tab-stop-list
884 This variable is the list of tab stop columns used by
885 `tab-to-tab-stops'. The elements should be integers in increasing
886 order. The tab stop columns need not be evenly spaced.
888 Use `M-x edit-tab-stops' to edit the location of tab stops
892 File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
894 Indentation-Based Motion Commands
895 ---------------------------------
897 These commands, primarily for interactive use, act based on the
898 indentation in the text.
900 - Command: back-to-indentation
901 This command moves point to the first non-whitespace character in
902 the current line (which is the line in which point is located).
905 - Command: backward-to-indentation arg
906 This command moves point backward ARG lines and then to the first
907 nonblank character on that line. It returns `nil'.
909 - Command: forward-to-indentation arg
910 This command moves point forward ARG lines and then to the first
911 nonblank character on that line. It returns `nil'.
914 File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
919 The case change commands described here work on text in the current
920 buffer. *Note Character Case::, for case conversion commands that work
921 on strings and characters. *Note Case Tables::, for how to customize
922 which characters are upper or lower case and how to convert them.
924 - Command: capitalize-region start end &optional buffer
925 This function capitalizes all words in the region defined by START
926 and END. To capitalize means to convert each word's first
927 character to upper case and convert the rest of each word to lower
928 case. The function returns `nil'.
930 If one end of the region is in the middle of a word, the part of
931 the word within the region is treated as an entire word.
933 When `capitalize-region' is called interactively, START and END
934 are point and the mark, with the smallest first.
936 ---------- Buffer: foo ----------
937 This is the contents of the 5th foo.
938 ---------- Buffer: foo ----------
940 (capitalize-region 1 44)
943 ---------- Buffer: foo ----------
944 This Is The Contents Of The 5th Foo.
945 ---------- Buffer: foo ----------
947 - Command: downcase-region start end &optional buffer
948 This function converts all of the letters in the region defined by
949 START and END to lower case. The function returns `nil'.
951 When `downcase-region' is called interactively, START and END are
952 point and the mark, with the smallest first.
954 - Command: upcase-region start end &optional buffer
955 This function converts all of the letters in the region defined by
956 START and END to upper case. The function returns `nil'.
958 When `upcase-region' is called interactively, START and END are
959 point and the mark, with the smallest first.
961 - Command: capitalize-word count &optional buffer
962 This function capitalizes COUNT words after point, moving point
963 over as it does. To capitalize means to convert each word's first
964 character to upper case and convert the rest of each word to lower
965 case. If COUNT is negative, the function capitalizes the -COUNT
966 previous words but does not move point. The value is `nil'.
968 If point is in the middle of a word, the part of the word before
969 point is ignored when moving forward. The rest is treated as an
972 When `capitalize-word' is called interactively, COUNT is set to
973 the numeric prefix argument.
975 - Command: downcase-word count &optional buffer
976 This function converts the COUNT words after point to all lower
977 case, moving point over as it does. If COUNT is negative, it
978 converts the -COUNT previous words but does not move point. The
981 When `downcase-word' is called interactively, COUNT is set to the
982 numeric prefix argument.
984 - Command: upcase-word count &optional buffer
985 This function converts the COUNT words after point to all upper
986 case, moving point over as it does. If COUNT is negative, it
987 converts the -COUNT previous words but does not move point. The
990 When `upcase-word' is called interactively, COUNT is set to the
991 numeric prefix argument.
994 File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
999 Text properties are an alternative interface to extents (*note
1000 Extents::), and are built on top of them. They are useful when you
1001 want to view textual properties as being attached to the characters
1002 themselves rather than to intervals of characters. The text property
1003 interface is compatible with FSF Emacs.
1005 Each character position in a buffer or a string can have a "text
1006 property list", much like the property list of a symbol (*note Property
1007 Lists::). The properties belong to a particular character at a
1008 particular place, such as, the letter `T' at the beginning of this
1009 sentence or the first `o' in `foo'--if the same character occurs in two
1010 different places, the two occurrences generally have different
1013 Each property has a name and a value. Both of these can be any Lisp
1014 object, but the name is normally a symbol. The usual way to access the
1015 property list is to specify a name and ask what value corresponds to it.
1017 Note that FSF Emacs also looks at the `category' property to find
1018 defaults for text properties. We consider this too bogus to implement.
1020 Copying text between strings and buffers preserves the properties
1021 along with the characters; this includes such diverse functions as
1022 `substring', `insert', and `buffer-substring'.
1026 * Examining Properties:: Looking at the properties of one character.
1027 * Changing Properties:: Setting the properties of a range of text.
1028 * Property Search:: Searching for where a property changes value.
1029 * Special Properties:: Particular properties with special meanings.
1030 * Saving Properties:: Saving text properties in files, and reading
1034 File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
1036 Examining Text Properties
1037 -------------------------
1039 The simplest way to examine text properties is to ask for the value of
1040 a particular property of a particular character. For that, use
1041 `get-text-property'. Use `text-properties-at' to get the entire
1042 property list of a character. *Note Property Search::, for functions
1043 to examine the properties of a number of characters at once.
1045 These functions handle both strings and buffers. (Keep in mind that
1046 positions in a string start from 0, whereas positions in a buffer start
1049 - Function: get-text-property pos prop &optional object at-flag
1050 This function returns the value of the PROP property of the
1051 character after position POS in OBJECT (a buffer or string). The
1052 argument OBJECT is optional and defaults to the current buffer.
1054 - Function: get-char-property pos prop &optional object at-flag
1055 This function is like `get-text-property', except that it checks
1056 all extents, not just text-property extents.
1059 - Function: text-properties-at position &optional object
1060 This function returns the entire property list of the character at
1061 POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
1062 defaults to the current buffer.
1064 - Variable: default-text-properties
1065 This variable holds a property list giving default values for text
1066 properties. Whenever a character does not specify a value for a
1067 property, the value stored in this list is used instead. Here is
1070 (setq default-text-properties '(foo 69))
1071 ;; Make sure character 1 has no properties of its own.
1072 (set-text-properties 1 2 nil)
1073 ;; What we get, when we ask, is the default value.
1074 (get-text-property 1 'foo)
1078 File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
1080 Changing Text Properties
1081 ------------------------
1083 The primitives for changing properties apply to a specified range of
1084 text. The function `set-text-properties' (see end of section) sets the
1085 entire property list of the text in that range; more often, it is
1086 useful to add, change, or delete just certain properties specified by
1089 Since text properties are considered part of the buffer's contents,
1090 and can affect how the buffer looks on the screen, any change in the
1091 text properties is considered a buffer modification. Buffer text
1092 property changes are undoable (*note Undo::).
1094 - Function: put-text-property start end prop value &optional object
1095 This function sets the PROP property to VALUE for the text between
1096 START and END in the string or buffer OBJECT. If OBJECT is `nil',
1097 it defaults to the current buffer.
1099 - Function: add-text-properties start end props &optional object
1100 This function modifies the text properties for the text between
1101 START and END in the string or buffer OBJECT. If OBJECT is `nil',
1102 it defaults to the current buffer.
1104 The argument PROPS specifies which properties to change. It
1105 should have the form of a property list (*note Property Lists::):
1106 a list whose elements include the property names followed
1107 alternately by the corresponding values.
1109 The return value is `t' if the function actually changed some
1110 property's value; `nil' otherwise (if PROPS is `nil' or its values
1111 agree with those in the text).
1113 For example, here is how to set the `comment' and `face'
1114 properties of a range of text:
1116 (add-text-properties START END
1117 '(comment t face highlight))
1119 - Function: remove-text-properties start end props &optional object
1120 This function deletes specified text properties from the text
1121 between START and END in the string or buffer OBJECT. If OBJECT
1122 is `nil', it defaults to the current buffer.
1124 The argument PROPS specifies which properties to delete. It
1125 should have the form of a property list (*note Property Lists::):
1126 a list whose elements are property names alternating with
1127 corresponding values. But only the names matter--the values that
1128 accompany them are ignored. For example, here's how to remove the
1131 (remove-text-properties START END '(face nil))
1133 The return value is `t' if the function actually changed some
1134 property's value; `nil' otherwise (if PROPS is `nil' or if no
1135 character in the specified text had any of those properties).
1137 - Function: set-text-properties start end props &optional object
1138 This function completely replaces the text property list for the
1139 text between START and END in the string or buffer OBJECT. If
1140 OBJECT is `nil', it defaults to the current buffer.
1142 The argument PROPS is the new property list. It should be a list
1143 whose elements are property names alternating with corresponding
1146 After `set-text-properties' returns, all the characters in the
1147 specified range have identical properties.
1149 If PROPS is `nil', the effect is to get rid of all properties from
1150 the specified range of text. Here's an example:
1152 (set-text-properties START END nil)
1154 See also the function `buffer-substring-without-properties' (*note
1155 Buffer Contents::) which copies text from the buffer but does not copy
1159 File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
1161 Property Search Functions
1162 -------------------------
1164 In typical use of text properties, most of the time several or many
1165 consecutive characters have the same value for a property. Rather than
1166 writing your programs to examine characters one by one, it is much
1167 faster to process chunks of text that have the same property value.
1169 Here are functions you can use to do this. They use `eq' for
1170 comparing property values. In all cases, OBJECT defaults to the
1173 For high performance, it's very important to use the LIMIT argument
1174 to these functions, especially the ones that search for a single
1175 property--otherwise, they may spend a long time scanning to the end of
1176 the buffer, if the property you are interested in does not change.
1178 Remember that a position is always between two characters; the
1179 position returned by these functions is between two characters with
1180 different properties.
1182 - Function: next-property-change pos &optional object limit
1183 The function scans the text forward from position POS in the
1184 string or buffer OBJECT till it finds a change in some text
1185 property, then returns the position of the change. In other
1186 words, it returns the position of the first character beyond POS
1187 whose properties are not identical to those of the character just
1190 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
1191 there is no property change before that point,
1192 `next-property-change' returns LIMIT.
1194 The value is `nil' if the properties remain unchanged all the way
1195 to the end of OBJECT and LIMIT is `nil'. If the value is
1196 non-`nil', it is a position greater than or equal to POS. The
1197 value equals POS only when LIMIT equals POS.
1199 Here is an example of how to scan the buffer by chunks of text
1200 within which all properties are constant:
1203 (let ((plist (text-properties-at (point)))
1205 (or (next-property-change (point) (current-buffer))
1207 Process text from point to NEXT-CHANGE...
1208 (goto-char next-change)))
1210 - Function: next-single-property-change pos prop &optional object limit
1211 The function scans the text forward from position POS in the
1212 string or buffer OBJECT till it finds a change in the PROP
1213 property, then returns the position of the change. In other
1214 words, it returns the position of the first character beyond POS
1215 whose PROP property differs from that of the character just after
1218 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
1219 there is no property change before that point,
1220 `next-single-property-change' returns LIMIT.
1222 The value is `nil' if the property remains unchanged all the way to
1223 the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
1224 it is a position greater than or equal to POS; it equals POS only
1225 if LIMIT equals POS.
1227 - Function: previous-property-change pos &optional object limit
1228 This is like `next-property-change', but scans backward from POS
1229 instead of forward. If the value is non-`nil', it is a position
1230 less than or equal to POS; it equals POS only if LIMIT equals POS.
1232 - Function: previous-single-property-change pos prop &optional object
1234 This is like `next-single-property-change', but scans backward from
1235 POS instead of forward. If the value is non-`nil', it is a
1236 position less than or equal to POS; it equals POS only if LIMIT
1239 - Function: text-property-any start end prop value &optional object
1240 This function returns non-`nil' if at least one character between
1241 START and END has a property PROP whose value is VALUE. More
1242 precisely, it returns the position of the first such character.
1243 Otherwise, it returns `nil'.
1245 The optional fifth argument, OBJECT, specifies the string or
1246 buffer to scan. Positions are relative to OBJECT. The default
1247 for OBJECT is the current buffer.
1249 - Function: text-property-not-all start end prop value &optional object
1250 This function returns non-`nil' if at least one character between
1251 START and END has a property PROP whose value differs from VALUE.
1252 More precisely, it returns the position of the first such
1253 character. Otherwise, it returns `nil'.
1255 The optional fifth argument, OBJECT, specifies the string or
1256 buffer to scan. Positions are relative to OBJECT. The default
1257 for OBJECT is the current buffer.
1260 File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
1262 Properties with Special Meanings
1263 --------------------------------
1265 The predefined properties are the same as those for extents. *Note
1266 Extent Properties::.
1269 File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
1271 Saving Text Properties in Files
1272 -------------------------------
1274 You can save text properties in files, and restore text properties when
1275 inserting the files, using these two hooks:
1277 - Variable: write-region-annotate-functions
1278 This variable's value is a list of functions for `write-region' to
1279 run to encode text properties in some fashion as annotations to
1280 the text being written in the file. *Note Writing to Files::.
1282 Each function in the list is called with two arguments: the start
1283 and end of the region to be written. These functions should not
1284 alter the contents of the buffer. Instead, they should return
1285 lists indicating annotations to write in the file in addition to
1286 the text in the buffer.
1288 Each function should return a list of elements of the form
1289 `(POSITION . STRING)', where POSITION is an integer specifying the
1290 relative position in the text to be written, and STRING is the
1291 annotation to add there.
1293 Each list returned by one of these functions must be already
1294 sorted in increasing order by POSITION. If there is more than one
1295 function, `write-region' merges the lists destructively into one
1298 When `write-region' actually writes the text from the buffer to the
1299 file, it intermixes the specified annotations at the corresponding
1300 positions. All this takes place without modifying the buffer.
1302 - Variable: after-insert-file-functions
1303 This variable holds a list of functions for `insert-file-contents'
1304 to call after inserting a file's contents. These functions should
1305 scan the inserted text for annotations, and convert them to the
1306 text properties they stand for.
1308 Each function receives one argument, the length of the inserted
1309 text; point indicates the start of that text. The function should
1310 scan that text for annotations, delete them, and create the text
1311 properties that the annotations specify. The function should
1312 return the updated length of the inserted text, as it stands after
1313 those changes. The value returned by one function becomes the
1314 argument to the next function.
1316 These functions should always return with point at the beginning of
1319 The intended use of `after-insert-file-functions' is for converting
1320 some sort of textual annotations into actual text properties. But
1321 other uses may be possible.
1323 We invite users to write Lisp programs to store and retrieve text
1324 properties in files, using these hooks, and thus to experiment with
1325 various data formats and find good ones. Eventually we hope users will
1326 produce good, general extensions we can install in Emacs.
1328 We suggest not trying to handle arbitrary Lisp objects as property
1329 names or property values--because a program that general is probably
1330 difficult to write, and slow. Instead, choose a set of possible data
1331 types that are reasonably flexible, and not too hard to encode.
1333 *Note Format Conversion::, for a related feature.
1336 File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
1338 Substituting for a Character Code
1339 =================================
1341 The following functions replace characters within a specified region
1342 based on their character codes.
1344 - Function: subst-char-in-region start end old-char new-char &optional
1346 This function replaces all occurrences of the character OLD-CHAR
1347 with the character NEW-CHAR in the region of the current buffer
1348 defined by START and END.
1350 If NOUNDO is non-`nil', then `subst-char-in-region' does not
1351 record the change for undo and does not mark the buffer as
1352 modified. This feature is used for controlling selective display
1353 (*note Selective Display::).
1355 `subst-char-in-region' does not move point and returns `nil'.
1357 ---------- Buffer: foo ----------
1358 This is the contents of the buffer before.
1359 ---------- Buffer: foo ----------
1361 (subst-char-in-region 1 20 ?i ?X)
1364 ---------- Buffer: foo ----------
1365 ThXs Xs the contents of the buffer before.
1366 ---------- Buffer: foo ----------
1368 - Function: translate-region start end table
1369 This function applies a translation table to the characters in the
1370 buffer between positions START and END. The translation table
1371 TABLE can be either a string, a vector, or a char-table.
1373 If TABLE is a string, its Nth element is the mapping for the
1374 character with code N.
1376 If TABLE is a vector, its Nth element is the mapping for character
1377 with code N. Legal mappings are characters, strings, or `nil'
1378 (meaning don't replace.)
1380 If TABLE is a char-table, its elements describe the mapping
1381 between characters and their replacements. The char-table should
1382 be of type `char' or `generic'.
1384 When the TABLE is a string or vector and its length is less than
1385 the total number of characters (256 without Mule), any characters
1386 with codes larger than the length of TABLE are not altered by the
1389 The return value of `translate-region' is the number of characters
1390 that were actually changed by the translation. This does not
1391 count characters that were mapped into themselves in the
1394 *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
1395 to be a string. This is still the case in FSF Emacs.
1397 The following example creates a char-table that is passed to
1398 `translate-region', which translates character `a' to `the letter
1399 a', removes character `b', and translates character `c' to newline.
1401 ---------- Buffer: foo ----------
1402 Here is a sentence in the buffer.
1403 ---------- Buffer: foo ----------
1405 (let ((table (make-char-table 'generic)))
1406 (put-char-table ?a "the letter a" table)
1407 (put-char-table ?b "" table)
1408 (put-char-table ?c ?\n table)
1409 (translate-region (point-min) (point-max) table))
1412 ---------- Buffer: foo ----------
1413 Here is the letter a senten
1415 ---------- Buffer: foo ----------
1418 File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
1423 A register is a sort of variable used in XEmacs editing that can hold a
1424 marker, a string, a rectangle, a window configuration (of one frame), or
1425 a frame configuration (of all frames). Each register is named by a
1426 single character. All characters, including control and meta characters
1427 (but with the exception of `C-g'), can be used to name registers.
1428 Thus, there are 255 possible registers. A register is designated in
1429 Emacs Lisp by a character that is its name.
1431 The functions in this section return unpredictable values unless
1434 - Variable: register-alist
1435 This variable is an alist of elements of the form `(NAME .
1436 CONTENTS)'. Normally, there is one element for each XEmacs
1437 register that has been used.
1439 The object NAME is a character (an integer) identifying the
1440 register. The object CONTENTS is a string, marker, or list
1441 representing the register contents. A string represents text
1442 stored in the register. A marker represents a position. A list
1443 represents a rectangle; its elements are strings, one per line of
1446 - Function: get-register register
1447 This function returns the contents of the register REGISTER, or
1448 `nil' if it has no contents.
1450 - Function: set-register register value
1451 This function sets the contents of register REGISTER to VALUE. A
1452 register can be set to any value, but the other register functions
1453 expect only certain data types. The return value is VALUE.
1455 - Command: view-register register
1456 This command displays what is contained in register REGISTER.
1458 - Command: insert-register register &optional beforep
1459 This command inserts contents of register REGISTER into the current
1462 Normally, this command puts point before the inserted text, and the
1463 mark after it. However, if the optional second argument BEFOREP
1464 is non-`nil', it puts the mark before and point after. You can
1465 pass a non-`nil' second argument BEFOREP to this function
1466 interactively by supplying any prefix argument.
1468 If the register contains a rectangle, then the rectangle is
1469 inserted with its upper left corner at point. This means that
1470 text is inserted in the current line and underneath it on
1473 If the register contains something other than saved text (a
1474 string) or a rectangle (a list), currently useless things happen.
1475 This may be changed in the future.
1478 File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
1480 Transposition of Text
1481 =====================
1483 This subroutine is used by the transposition commands.
1485 - Function: transpose-regions start1 end1 start2 end2 &optional
1487 This function exchanges two nonoverlapping portions of the buffer.
1488 Arguments START1 and END1 specify the bounds of one portion and
1489 arguments START2 and END2 specify the bounds of the other portion.
1491 Normally, `transpose-regions' relocates markers with the transposed
1492 text; a marker previously positioned within one of the two
1493 transposed portions moves along with that portion, thus remaining
1494 between the same two characters in their new position. However,
1495 if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
1496 this--it leaves all markers unrelocated.
1499 File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
1504 These hook variables let you arrange to take notice of all changes in
1505 all buffers (or in a particular buffer, if you make them buffer-local).
1507 The functions you use in these hooks should save and restore the
1508 match data if they do anything that uses regular expressions;
1509 otherwise, they will interfere in bizarre ways with the editing
1510 operations that call them.
1512 Buffer changes made while executing the following hooks don't
1513 themselves cause any change hooks to be invoked.
1515 - Variable: before-change-functions
1516 This variable holds a list of a functions to call before any buffer
1517 modification. Each function gets two arguments, the beginning and
1518 end of the region that is about to change, represented as
1519 integers. The buffer that is about to change is always the
1522 - Variable: after-change-functions
1523 This variable holds a list of a functions to call after any buffer
1524 modification. Each function receives three arguments: the
1525 beginning and end of the region just changed, and the length of
1526 the text that existed before the change. (To get the current
1527 length, subtract the region beginning from the region end.) All
1528 three arguments are integers. The buffer that's about to change
1529 is always the current buffer.
1531 - Variable: before-change-function
1532 This obsolete variable holds one function to call before any buffer
1533 modification (or `nil' for no function). It is called just like
1534 the functions in `before-change-functions'.
1536 - Variable: after-change-function
1537 This obsolete variable holds one function to call after any buffer
1538 modification (or `nil' for no function). It is called just like
1539 the functions in `after-change-functions'.
1541 - Variable: first-change-hook
1542 This variable is a normal hook that is run whenever a buffer is
1543 changed that was previously in the unmodified state.
1546 File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text
1548 Textual transformations--MD5 and base64 support
1549 ===============================================
1551 Some textual operations inherently require examining each character in
1552 turn, and performing arithmetic operations on them. Such operations
1553 can, of course, be implemented in Emacs Lisp, but tend to be very slow
1554 for large portions of text or data. This is why some of them are
1555 implemented in C, with an appropriate interface for Lisp programmers.
1556 Examples of algorithms thus provided are MD5 and base64 support.
1558 MD5 is an algorithm for calculating message digests, as described in
1559 rfc1321. Given a message of arbitrary length, MD5 produces a 128-bit
1560 "fingerprint" ("message digest") corresponding to that message. It is
1561 considered computationally infeasible to produce two messages having
1562 the same MD5 digest, or to produce a message having a prespecified
1563 target digest. MD5 is used heavily by various authentication schemes.
1565 Emacs Lisp interface to MD5 consists of a single function `md5':
1567 - Function: md5 object &optional start end coding noerror
1568 This function returns the MD5 message digest of OBJECT, a buffer
1571 Optional arguments START and END denote positions for computing
1572 the digest of a portion of OBJECT.
1574 The optional CODING argument specifies the coding system the text
1575 is to be represented in while computing the digest. If
1576 unspecified, it defaults to the current format of the data, or is
1579 If NOERROR is non-`nil', silently assume binary coding if the
1580 guesswork fails. Normally, an error is signaled in such case.
1582 CODING and NOERROR arguments are meaningful only in XEmacsen with
1583 file-coding or Mule support. Otherwise, they are ignored. Some
1586 ;; Calculate the digest of the entire buffer
1587 (md5 (current-buffer))
1588 => "8842b04362899b1cda8d2d126dc11712"
1590 ;; Calculate the digest of the current line
1591 (md5 (current-buffer) (point-at-bol) (point-at-eol))
1592 => "60614d21e9dee27dfdb01fa4e30d6d00"
1594 ;; Calculate the digest of your name and email address
1595 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
1596 => "0a2188c40fd38922d941fe6032fce516"
1598 Base64 is a portable encoding for arbitrary sequences of octets, in a
1599 form that need not be readable by humans. It uses a 65-character subset
1600 of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
1601 binary bodies, and to encode binary characters in message headers.
1603 The Lisp interface to base64 consists of four functions:
1605 - Command: base64-encode-region start end &optional no-line-break
1606 This function encodes the region between START and END of the
1607 current buffer to base64 format. This means that the original
1608 region is deleted, and replaced with its base64 equivalent.
1610 Normally, encoded base64 output is multi-line, with 76-character
1611 lines. If NO-LINE-BREAK is non-`nil', newlines will not be
1612 inserted, resulting in single-line output.
1614 Mule note: you should make sure that you convert the multibyte
1615 characters (those that do not fit into 0-255 range) to something
1616 else, because they cannot be meaningfully converted to base64. If
1617 the `base64-encode-region' encounters such characters, it will
1620 `base64-encode-region' returns the length of the encoded text.
1622 ;; Encode the whole buffer in base64
1623 (base64-encode-region (point-min) (point-max))
1625 The function can also be used interactively, in which case it
1626 works on the currently active region.
1628 - Function: base64-encode-string string &optional no-line-break
1629 This function encodes STRING to base64, and returns the encoded
1632 Normally, encoded base64 output is multi-line, with 76-character
1633 lines. If NO-LINE-BREAK is non-`nil', newlines will not be
1634 inserted, resulting in single-line output.
1636 For Mule, the same considerations apply as for
1637 `base64-encode-region'.
1639 (base64-encode-string "fubar")
1642 - Command: base64-decode-region start end
1643 This function decodes the region between START and END of the
1644 current buffer. The region should be in base64 encoding.
1646 If the region was decoded correctly, `base64-decode-region' returns
1647 the length of the decoded region. If the decoding failed, `nil' is
1650 ;; Decode a base64 buffer, and replace it with the decoded version
1651 (base64-decode-region (point-min) (point-max))
1653 - Function: base64-decode-string string
1654 This function decodes STRING to base64, and returns the decoded
1655 string. STRING should be valid base64-encoded text.
1657 If encoding was not possible, `nil' is returned.
1659 (base64-decode-string "ZnViYXI=")
1662 (base64-decode-string "totally bogus")
1666 File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top
1668 Searching and Matching
1669 **********************
1671 XEmacs provides two ways to search through a buffer for specified text:
1672 exact string searches and regular expression searches. After a regular
1673 expression search, you can examine the "match data" to determine which
1674 text matched the whole regular expression or various portions of it.
1678 * String Search:: Search for an exact match.
1679 * Regular Expressions:: Describing classes of strings.
1680 * Regexp Search:: Searching for a match for a regexp.
1681 * POSIX Regexps:: Searching POSIX-style for the longest match.
1682 * Search and Replace:: Internals of `query-replace'.
1683 * Match Data:: Finding out which part of the text matched
1684 various parts of a regexp, after regexp search.
1685 * Searching and Case:: Case-independent or case-significant searching.
1686 * Standard Regexps:: Useful regexps for finding sentences, pages,...
1688 The `skip-chars...' functions also perform a kind of searching.
1689 *Note Skipping Characters::.
1692 File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching
1694 Searching for Strings
1695 =====================
1697 These are the primitive functions for searching through the text in a
1698 buffer. They are meant for use in programs, but you may call them
1699 interactively. If you do so, they prompt for the search string; LIMIT
1700 and NOERROR are set to `nil', and COUNT is set to 1.
1702 - Command: search-forward string &optional limit noerror count buffer
1703 This function searches forward from point for an exact match for
1704 STRING. If successful, it sets point to the end of the occurrence
1705 found, and returns the new value of point. If no match is found,
1706 the value and side effects depend on NOERROR (see below).
1708 In the following example, point is initially at the beginning of
1709 the line. Then `(search-forward "fox")' moves point after the last
1712 ---------- Buffer: foo ----------
1713 -!-The quick brown fox jumped over the lazy dog.
1714 ---------- Buffer: foo ----------
1716 (search-forward "fox")
1719 ---------- Buffer: foo ----------
1720 The quick brown fox-!- jumped over the lazy dog.
1721 ---------- Buffer: foo ----------
1723 The argument LIMIT specifies the upper bound to the search. (It
1724 must be a position in the current buffer.) No match extending
1725 after that position is accepted. If LIMIT is omitted or `nil', it
1726 defaults to the end of the accessible portion of the buffer.
1728 What happens when the search fails depends on the value of
1729 NOERROR. If NOERROR is `nil', a `search-failed' error is
1730 signaled. If NOERROR is `t', `search-forward' returns `nil' and
1731 does nothing. If NOERROR is neither `nil' nor `t', then
1732 `search-forward' moves point to the upper bound and returns `nil'.
1733 (It would be more consistent now to return the new position of
1734 point in that case, but some programs may depend on a value of
1737 If COUNT is supplied (it must be an integer), then the search is
1738 repeated that many times (each time starting at the end of the
1739 previous time's match). If COUNT is negative, the search
1740 direction is backward. If the successive searches succeed, the
1741 function succeeds, moving point and returning its new value.
1742 Otherwise the search fails.
1744 BUFFER is the buffer to search in, and defaults to the current
1747 - Command: search-backward string &optional limit noerror count buffer
1748 This function searches backward from point for STRING. It is just
1749 like `search-forward' except that it searches backwards and leaves
1750 point at the beginning of the match.
1752 - Command: word-search-forward string &optional limit noerror count
1754 This function searches forward from point for a "word" match for
1755 STRING. If it finds a match, it sets point to the end of the
1756 match found, and returns the new value of point.
1758 Word matching regards STRING as a sequence of words, disregarding
1759 punctuation that separates them. It searches the buffer for the
1760 same sequence of words. Each word must be distinct in the buffer
1761 (searching for the word `ball' does not match the word `balls'),
1762 but the details of punctuation and spacing are ignored (searching
1763 for `ball boy' does match `ball. Boy!').
1765 In this example, point is initially at the beginning of the
1766 buffer; the search leaves it between the `y' and the `!'.
1768 ---------- Buffer: foo ----------
1769 -!-He said "Please! Find
1771 ---------- Buffer: foo ----------
1773 (word-search-forward "Please find the ball, boy.")
1776 ---------- Buffer: foo ----------
1777 He said "Please! Find
1779 ---------- Buffer: foo ----------
1781 If LIMIT is non-`nil' (it must be a position in the current
1782 buffer), then it is the upper bound to the search. The match
1783 found must not extend after that position.
1785 If NOERROR is `nil', then `word-search-forward' signals an error
1786 if the search fails. If NOERROR is `t', then it returns `nil'
1787 instead of signaling an error. If NOERROR is neither `nil' nor
1788 `t', it moves point to LIMIT (or the end of the buffer) and
1791 If COUNT is non-`nil', then the search is repeated that many
1792 times. Point is positioned at the end of the last match.
1794 BUFFER is the buffer to search in, and defaults to the current
1797 - Command: word-search-backward string &optional limit noerror count
1799 This function searches backward from point for a word match to
1800 STRING. This function is just like `word-search-forward' except
1801 that it searches backward and normally leaves point at the
1802 beginning of the match.
1805 File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching
1810 A "regular expression" ("regexp", for short) is a pattern that denotes
1811 a (possibly infinite) set of strings. Searching for matches for a
1812 regexp is a very powerful operation. This section explains how to write
1813 regexps; the following section says how to search for them.
1815 To gain a thorough understanding of regular expressions and how to
1816 use them to best advantage, we recommend that you study `Mastering
1817 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
1818 1997'. (It's known as the "Hip Owls" book, because of the picture on its
1819 cover.) You might also read the manuals to *Note (gawk)Top::, *Note
1820 (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
1821 (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
1822 regular expressions.
1824 The XEmacs regular expression syntax most closely resembles that of
1825 `ed', or `grep', the GNU versions of which all utilize the GNU `regex'
1826 library. XEmacs' version of `regex' has recently been extended with
1827 some Perl-like capabilities, described in the next section.
1831 * Syntax of Regexps:: Rules for writing regular expressions.
1832 * Regexp Example:: Illustrates regular expression syntax.
1835 File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions
1837 Syntax of Regular Expressions
1838 -----------------------------
1840 Regular expressions have a syntax in which a few characters are special
1841 constructs and the rest are "ordinary". An ordinary character is a
1842 simple regular expression that matches that character and nothing else.
1843 The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
1844 `\'; no new special characters will be defined in the future. Any
1845 other character appearing in a regular expression is ordinary, unless a
1848 For example, `f' is not a special character, so it is ordinary, and
1849 therefore `f' is a regular expression that matches the string `f' and
1850 no other string. (It does _not_ match the string `ff'.) Likewise, `o'
1851 is a regular expression that matches only `o'.
1853 Any two regular expressions A and B can be concatenated. The result
1854 is a regular expression that matches a string if A matches some amount
1855 of the beginning of that string and B matches the rest of the string.
1857 As a simple example, we can concatenate the regular expressions `f'
1858 and `o' to get the regular expression `fo', which matches only the
1859 string `fo'. Still trivial. To do something more powerful, you need
1860 to use one of the special characters. Here is a list of them:
1863 is a special character that matches any single character except a
1864 newline. Using concatenation, we can make regular expressions
1865 like `a.b', which matches any three-character string that begins
1866 with `a' and ends with `b'.
1869 is not a construct by itself; it is a quantifying suffix operator
1870 that means to repeat the preceding regular expression as many
1871 times as possible. In `fo*', the `*' applies to the `o', so `fo*'
1872 matches one `f' followed by any number of `o's. The case of zero
1873 `o's is allowed: `fo*' does match `f'.
1875 `*' always applies to the _smallest_ possible preceding
1876 expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
1878 The matcher processes a `*' construct by matching, immediately, as
1879 many repetitions as can be found; it is "greedy". Then it
1880 continues with the rest of the pattern. If that fails,
1881 backtracking occurs, discarding some of the matches of the
1882 `*'-modified construct in case that makes it possible to match the
1883 rest of the pattern. For example, in matching `ca*ar' against the
1884 string `caaar', the `a*' first tries to match all three `a's; but
1885 the rest of the pattern is `ar' and there is only `r' left to
1886 match, so this try fails. The next alternative is for `a*' to
1887 match only two `a's. With this choice, the rest of the regexp
1888 matches successfully.
1890 Nested repetition operators can be extremely slow if they specify
1891 backtracking loops. For example, it could take hours for the
1892 regular expression `\(x+y*\)*a' to match the sequence
1893 `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
1894 Emacs must try each imaginable way of grouping the 35 `x''s before
1895 concluding that none of them can work. To make sure your regular
1896 expressions run fast, check nested repetitions carefully.
1899 is a quantifying suffix operator similar to `*' except that the
1900 preceding expression must match at least once. It is also
1901 "greedy". So, for example, `ca+r' matches the strings `car' and
1902 `caaaar' but not the string `cr', whereas `ca*r' matches all three
1906 is a quantifying suffix operator similar to `*', except that the
1907 preceding expression can match either once or not at all. For
1908 example, `ca?r' matches `car' or `cr', but does not match anything
1912 works just like `*', except that rather than matching the longest
1913 match, it matches the shortest match. `*?' is known as a
1914 "non-greedy" quantifier, a regexp construct borrowed from Perl.
1916 This construct is very useful for when you want to match the text
1917 inside a pair of delimiters. For instance, `/\*.*?\*/' will match
1918 C comments in a string. This could not easily be achieved without
1919 the use of a non-greedy quantifier.
1921 This construct has not been available prior to XEmacs 20.4. It is
1922 not available in FSF Emacs.
1925 is the non-greedy version of `+'.
1928 is the non-greedy version of `?'.
1931 serves as an interval quantifier, analogous to `*' or `+', but
1932 specifies that the expression must match at least N times, but no
1933 more than M times. This syntax is supported by most Unix regexp
1934 utilities, and has been introduced to XEmacs for the version 20.3.
1936 Unfortunately, the non-greedy version of this quantifier does not
1937 exist currently, although it does in Perl.
1940 `[' begins a "character set", which is terminated by a `]'. In
1941 the simplest case, the characters between the two brackets form
1942 the set. Thus, `[ad]' matches either one `a' or one `d', and
1943 `[ad]*' matches any string composed of just `a's and `d's
1944 (including the empty string), from which it follows that `c[ad]*r'
1945 matches `cr', `car', `cdr', `caddaar', etc.
1947 The usual regular expression special characters are not special
1948 inside a character set. A completely different set of special
1949 characters exists inside character sets: `]', `-' and `^'.
1951 `-' is used for ranges of characters. To write a range, write two
1952 characters with a `-' between them. Thus, `[a-z]' matches any
1953 lower case letter. Ranges may be intermixed freely with individual
1954 characters, as in `[a-z$%.]', which matches any lower case letter
1955 or `$', `%', or a period.
1957 To include a `]' in a character set, make it the first character.
1958 For example, `[]a]' matches `]' or `a'. To include a `-', write
1959 `-' as the first character in the set, or put it immediately after
1960 a range. (You can replace one individual character C with the
1961 range `C-C' to make a place to put the `-'.) There is no way to
1962 write a set containing just `-' and `]'.
1964 To include `^' in a set, put it anywhere but at the beginning of
1968 `[^' begins a "complement character set", which matches any
1969 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
1970 all characters _except_ letters and digits.
1972 `^' is not special in a character set unless it is the first
1973 character. The character following the `^' is treated as if it
1974 were first (thus, `-' and `]' are not special there).
1976 Note that a complement character set can match a newline, unless
1977 newline is mentioned as one of the characters not to match.
1980 is a special character that matches the empty string, but only at
1981 the beginning of a line in the text being matched. Otherwise it
1982 fails to match anything. Thus, `^foo' matches a `foo' that occurs
1983 at the beginning of a line.
1985 When matching a string instead of a buffer, `^' matches at the
1986 beginning of the string or after a newline character `\n'.
1989 is similar to `^' but matches only at the end of a line. Thus,
1990 `x+$' matches a string of one `x' or more at the end of a line.
1992 When matching a string instead of a buffer, `$' matches at the end
1993 of the string or before a newline character `\n'.
1996 has two functions: it quotes the special characters (including
1997 `\'), and it introduces additional special constructs.
1999 Because `\' quotes special characters, `\$' is a regular
2000 expression that matches only `$', and `\[' is a regular expression
2001 that matches only `[', and so on.
2003 Note that `\' also has special meaning in the read syntax of Lisp
2004 strings (*note String Type::), and must be quoted with `\'. For
2005 example, the regular expression that matches the `\' character is
2006 `\\'. To write a Lisp string that contains the characters `\\',
2007 Lisp syntax requires you to quote each `\' with another `\'.
2008 Therefore, the read syntax for a regular expression matching `\'
2011 *Please note:* For historical compatibility, special characters are
2012 treated as ordinary ones if they are in contexts where their special
2013 meanings make no sense. For example, `*foo' treats `*' as ordinary
2014 since there is no preceding expression on which the `*' can act. It is
2015 poor practice to depend on this behavior; quote the special character
2016 anyway, regardless of where it appears.
2018 For the most part, `\' followed by any character matches only that
2019 character. However, there are several exceptions: characters that,
2020 when preceded by `\', are special constructs. Such characters are
2021 always ordinary when encountered on their own. Here is a table of `\'
2025 specifies an alternative. Two regular expressions A and B with
2026 `\|' in between form an expression that matches anything that
2027 either A or B matches.
2029 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
2031 `\|' applies to the largest possible surrounding expressions.
2032 Only a surrounding `\( ... \)' grouping can limit the grouping
2035 Full backtracking capability exists to handle multiple uses of
2039 is a grouping construct that serves three purposes:
2041 1. To enclose a set of `\|' alternatives for other operations.
2042 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
2044 2. To enclose an expression for a suffix operator such as `*' to
2045 act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
2046 (zero or more) number of `na' strings.
2048 3. To record a matched substring for future reference.
2050 This last application is not a consequence of the idea of a
2051 parenthetical grouping; it is a separate feature that happens to be
2052 assigned as a second meaning to the same `\( ... \)' construct
2053 because there is no conflict in practice between the two meanings.
2054 Here is an explanation of this feature:
2057 matches the same text that matched the DIGITth occurrence of a `\(
2060 In other words, after the end of a `\( ... \)' construct. the
2061 matcher remembers the beginning and end of the text matched by that
2062 construct. Then, later on in the regular expression, you can use
2063 `\' followed by DIGIT to match that same text, whatever it may
2066 The strings matching the first nine `\( ... \)' constructs
2067 appearing in a regular expression are assigned numbers 1 through 9
2068 in the order that the open parentheses appear in the regular
2069 expression. So you can use `\1' through `\9' to refer to the text
2070 matched by the corresponding `\( ... \)' constructs.
2072 For example, `\(.*\)\1' matches any newline-free string that is
2073 composed of two identical halves. The `\(.*\)' matches the first
2074 half, which may be anything, but the `\1' that follows must match
2075 the same exact text.
2078 is called a "shy" grouping operator, and it is used just like `\(
2079 ... \)', except that it does not cause the matched substring to be
2080 recorded for future reference.
2082 This is useful when you need a lot of grouping `\( ... \)'
2083 constructs, but only want to remember one or two - or if you have
2084 more than nine groupings and need to use backreferences to refer to
2085 the groupings at the end.
2087 Using `\(?: ... \)' rather than `\( ... \)' when you don't need
2088 the captured substrings ought to speed up your programs some,
2089 since it shortens the code path followed by the regular expression
2090 engine, as well as the amount of memory allocation and string
2091 copying it must do. The actual performance gain to be observed
2092 has not been measured or quantified as of this writing.
2094 The shy grouping operator has been borrowed from Perl, and has not
2095 been available prior to XEmacs 20.3, nor is it available in FSF
2099 matches any word-constituent character. The editor syntax table
2100 determines which characters these are. *Note Syntax Tables::.
2103 matches any character that is not a word constituent.
2106 matches any character whose syntax is CODE. Here CODE is a
2107 character that represents a syntax code: thus, `w' for word
2108 constituent, `-' for whitespace, `(' for open parenthesis, etc.
2109 *Note Syntax Tables::, for a list of syntax codes and the
2110 characters that stand for them.
2113 matches any character whose syntax is not CODE.
2115 The following regular expression constructs match the empty
2116 string--that is, they don't use up any characters--but whether they
2117 match depends on the context.
2120 matches the empty string, but only at the beginning of the buffer
2121 or string being matched against.
2124 matches the empty string, but only at the end of the buffer or
2125 string being matched against.
2128 matches the empty string, but only at point. (This construct is
2129 not defined when matching against a string.)
2132 matches the empty string, but only at the beginning or end of a
2133 word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
2134 separate word. `\bballs?\b' matches `ball' or `balls' as a
2138 matches the empty string, but _not_ at the beginning or end of a
2142 matches the empty string, but only at the beginning of a word.
2145 matches the empty string, but only at the end of a word.
2147 Not every string is a valid regular expression. For example, a
2148 string with unbalanced square brackets is invalid (with a few
2149 exceptions, such as `[]]'), and so is a string that ends with a single
2150 `\'. If an invalid regular expression is passed to any of the search
2151 functions, an `invalid-regexp' error is signaled.
2153 - Function: regexp-quote string
2154 This function returns a regular expression string that matches
2155 exactly STRING and nothing else. This allows you to request an
2156 exact string match when calling a function that wants a regular
2159 (regexp-quote "^The cat$")
2162 One use of `regexp-quote' is to combine an exact string match with
2163 context described as a regular expression. For example, this
2164 searches for the string that is the value of `string', surrounded
2168 (concat "\\s-" (regexp-quote string) "\\s-"))
2171 File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
2173 Complex Regexp Example
2174 ----------------------
2176 Here is a complicated regexp, used by XEmacs to recognize the end of a
2177 sentence together with any whitespace that follows. It is the value of
2178 the variable `sentence-end'.
2180 First, we show the regexp as a string in Lisp syntax to distinguish
2181 spaces from tab characters. The string constant begins and ends with a
2182 double-quote. `\"' stands for a double-quote as part of the string,
2183 `\\' for a backslash as part of the string, `\t' for a tab and `\n' for
2186 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
2188 In contrast, if you evaluate the variable `sentence-end', you will
2193 "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
2196 In this output, tab and newline appear as themselves.
2198 This regular expression contains four parts in succession and can be
2199 deciphered as follows:
2202 The first part of the pattern is a character set that matches any
2203 one of three characters: period, question mark, and exclamation
2204 mark. The match must begin with one of these three characters.
2207 The second part of the pattern matches any closing braces and
2208 quotation marks, zero or more of them, that may follow the period,
2209 question mark or exclamation mark. The `\"' is Lisp syntax for a
2210 double-quote in a string. The `*' at the end indicates that the
2211 immediately preceding regular expression (a character set, in this
2212 case) may be repeated zero or more times.
2214 `\\($\\| $\\|\t\\| \\)'
2215 The third part of the pattern matches the whitespace that follows
2216 the end of a sentence: the end of a line, or a tab, or two spaces.
2217 The double backslashes mark the parentheses and vertical bars as
2218 regular expression syntax; the parentheses delimit a group and the
2219 vertical bars separate alternatives. The dollar sign is used to
2220 match the end of a line.
2223 Finally, the last part of the pattern matches any additional
2224 whitespace beyond the minimum needed to end a sentence.
2227 File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
2229 Regular Expression Searching
2230 ============================
2232 In XEmacs, you can search for the next match for a regexp either
2233 incrementally or not. Incremental search commands are described in the
2234 `The XEmacs Lisp Reference Manual'. *Note Regular Expression Search:
2235 (xemacs)Regexp Search. Here we describe only the search functions
2236 useful in programs. The principal one is `re-search-forward'.
2238 - Command: re-search-forward regexp &optional limit noerror count
2240 This function searches forward in the current buffer for a string
2241 of text that is matched by the regular expression REGEXP. The
2242 function skips over any amount of text that is not matched by
2243 REGEXP, and leaves point at the end of the first match found. It
2244 returns the new value of point.
2246 If LIMIT is non-`nil' (it must be a position in the current
2247 buffer), then it is the upper bound to the search. No match
2248 extending after that position is accepted.
2250 What happens when the search fails depends on the value of
2251 NOERROR. If NOERROR is `nil', a `search-failed' error is
2252 signaled. If NOERROR is `t', `re-search-forward' does nothing and
2253 returns `nil'. If NOERROR is neither `nil' nor `t', then
2254 `re-search-forward' moves point to LIMIT (or the end of the
2255 buffer) and returns `nil'.
2257 If COUNT is supplied (it must be a positive number), then the
2258 search is repeated that many times (each time starting at the end
2259 of the previous time's match). If these successive searches
2260 succeed, the function succeeds, moving point and returning its new
2261 value. Otherwise the search fails.
2263 In the following example, point is initially before the `T'.
2264 Evaluating the search call moves point to the end of that line
2265 (between the `t' of `hat' and the newline).
2267 ---------- Buffer: foo ----------
2268 I read "-!-The cat in the hat
2270 ---------- Buffer: foo ----------
2272 (re-search-forward "[a-z]+" nil t 5)
2275 ---------- Buffer: foo ----------
2276 I read "The cat in the hat-!-
2278 ---------- Buffer: foo ----------
2280 - Command: re-search-backward regexp &optional limit noerror count
2282 This function searches backward in the current buffer for a string
2283 of text that is matched by the regular expression REGEXP, leaving
2284 point at the beginning of the first text found.
2286 This function is analogous to `re-search-forward', but they are not
2287 simple mirror images. `re-search-forward' finds the match whose
2288 beginning is as close as possible to the starting point. If
2289 `re-search-backward' were a perfect mirror image, it would find the
2290 match whose end is as close as possible. However, in fact it
2291 finds the match whose beginning is as close as possible. The
2292 reason is that matching a regular expression at a given spot
2293 always works from beginning to end, and starts at a specified
2296 A true mirror-image of `re-search-forward' would require a special
2297 feature for matching regexps from end to beginning. It's not
2298 worth the trouble of implementing that.
2300 - Function: string-match regexp string &optional start buffer
2301 This function returns the index of the start of the first match for
2302 the regular expression REGEXP in STRING, or `nil' if there is no
2303 match. If START is non-`nil', the search starts at that index in
2306 Optional arg BUFFER controls how case folding is done (according
2307 to the value of `case-fold-search' in BUFFER and BUFFER's case
2308 tables) and defaults to the current buffer.
2313 "quick" "The quick brown fox jumped quickly.")
2316 "quick" "The quick brown fox jumped quickly." 8)
2319 The index of the first character of the string is 0, the index of
2320 the second character is 1, and so on.
2322 After this function returns, the index of the first character
2323 beyond the match is available as `(match-end 0)'. *Note Match
2327 "quick" "The quick brown fox jumped quickly." 8)
2333 - Function: split-string string &optional pattern
2334 This function splits STRING to substrings delimited by PATTERN,
2335 and returns a list of substrings. If PATTERN is omitted, it
2336 defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
2339 (split-string "foo bar")
2342 (split-string "something")
2345 (split-string "a:b:c" ":")
2348 (split-string ":a::b:c" ":")
2349 => ("" "a" "" "b" "c")
2351 - Function: split-path path
2352 This function splits a search path into a list of strings. The
2353 path components are separated with the characters specified with
2354 `path-separator'. Under Unix, `path-separator' will normally be
2355 `:', while under Windows, it will be `;'.
2357 - Function: looking-at regexp &optional buffer
2358 This function determines whether the text in the current buffer
2359 directly following point matches the regular expression REGEXP.
2360 "Directly following" means precisely that: the search is
2361 "anchored" and it can succeed only starting with the first
2362 character following point. The result is `t' if so, `nil'
2365 This function does not move point, but it updates the match data,
2366 which you can access using `match-beginning' and `match-end'.
2369 In this example, point is located directly before the `T'. If it
2370 were anywhere else, the result would be `nil'.
2372 ---------- Buffer: foo ----------
2373 I read "-!-The cat in the hat
2375 ---------- Buffer: foo ----------
2377 (looking-at "The cat in the hat$")
2381 File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
2383 POSIX Regular Expression Searching
2384 ==================================
2386 The usual regular expression functions do backtracking when necessary
2387 to handle the `\|' and repetition constructs, but they continue this
2388 only until they find _some_ match. Then they succeed and report the
2391 This section describes alternative search functions which perform the
2392 full backtracking specified by the POSIX standard for regular expression
2393 matching. They continue backtracking until they have tried all
2394 possibilities and found all matches, so they can report the longest
2395 match, as required by POSIX. This is much slower, so use these
2396 functions only when you really need the longest match.
2398 In Emacs versions prior to 19.29, these functions did not exist, and
2399 the functions described above implemented full POSIX backtracking.
2401 - Command: posix-search-forward regexp &optional limit noerror count
2403 This is like `re-search-forward' except that it performs the full
2404 backtracking specified by the POSIX standard for regular expression
2407 - Command: posix-search-backward regexp &optional limit noerror count
2409 This is like `re-search-backward' except that it performs the full
2410 backtracking specified by the POSIX standard for regular expression
2413 - Function: posix-looking-at regexp &optional buffer
2414 This is like `looking-at' except that it performs the full
2415 backtracking specified by the POSIX standard for regular expression
2418 - Function: posix-string-match regexp string &optional start buffer
2419 This is like `string-match' except that it performs the full
2420 backtracking specified by the POSIX standard for regular expression
2423 Optional arg BUFFER controls how case folding is done (according
2424 to the value of `case-fold-search' in BUFFER and BUFFER's case
2425 tables) and defaults to the current buffer.
2428 File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
2433 - Function: perform-replace from-string replacements query-flag
2434 regexp-flag delimited-flag &optional repeat-count map
2435 This function is the guts of `query-replace' and related commands.
2436 It searches for occurrences of FROM-STRING and replaces some or
2437 all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
2438 otherwise, it asks the user what to do about each one.
2440 If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
2441 regular expression; otherwise, it must match literally. If
2442 DELIMITED-FLAG is non-`nil', then only replacements surrounded by
2443 word boundaries are considered.
2445 The argument REPLACEMENTS specifies what to replace occurrences
2446 with. If it is a string, that string is used. It can also be a
2447 list of strings, to be used in cyclic order.
2449 If REPEAT-COUNT is non-`nil', it should be an integer. Then it
2450 specifies how many times to use each of the strings in the
2451 REPLACEMENTS list before advancing cyclicly to the next one.
2453 Normally, the keymap `query-replace-map' defines the possible user
2454 responses for queries. The argument MAP, if non-`nil', is a
2455 keymap to use instead of `query-replace-map'.
2457 - Variable: query-replace-map
2458 This variable holds a special keymap that defines the valid user
2459 responses for `query-replace' and related functions, as well as
2460 `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways:
2462 * The "key bindings" are not commands, just symbols that are
2463 meaningful to the functions that use this map.
2465 * Prefix keys are not supported; each key binding must be for a
2466 single event key sequence. This is because the functions
2467 don't use read key sequence to get the input; instead, they
2468 read a single event and look it up "by hand."
2470 Here are the meaningful "bindings" for `query-replace-map'. Several
2471 of them are meaningful only for `query-replace' and friends.
2474 Do take the action being considered--in other words, "yes."
2477 Do not take action for this question--in other words, "no."
2480 Answer this question "no," and give up on the entire series of
2481 questions, assuming that the answers will be "no."
2484 Answer this question "yes," and give up on the entire series of
2485 questions, assuming that subsequent answers will be "no."
2488 Answer this question "yes," but show the results--don't advance yet
2489 to the next question.
2492 Answer this question and all subsequent questions in the series
2493 with "yes," without further user interaction.
2496 Move back to the previous place that a question was asked about.
2499 Enter a recursive edit to deal with this question--instead of any
2500 other action that would normally be taken.
2503 Delete the text being considered, then enter a recursive edit to
2507 Redisplay and center the window, then ask the same question again.
2510 Perform a quit right away. Only `y-or-n-p' and related functions
2514 Display some help, then ask again.
2517 File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
2522 XEmacs keeps track of the positions of the start and end of segments of
2523 text found during a regular expression search. This means, for example,
2524 that you can search for a complex pattern, such as a date in an Rmail
2525 message, and then extract parts of the match under control of the
2528 Because the match data normally describe the most recent search only,
2529 you must be careful not to do another search inadvertently between the
2530 search you wish to refer back to and the use of the match data. If you
2531 can't avoid another intervening search, you must save and restore the
2532 match data around it, to prevent it from being overwritten.
2536 * Simple Match Data:: Accessing single items of match data,
2537 such as where a particular subexpression started.
2538 * Replacing Match:: Replacing a substring that was matched.
2539 * Entire Match Data:: Accessing the entire match data at once, as a list.
2540 * Saving Match Data:: Saving and restoring the match data.
2543 File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
2545 Simple Match Data Access
2546 ------------------------
2548 This section explains how to use the match data to find out what was
2549 matched by the last search or match operation.
2551 You can ask about the entire matching text, or about a particular
2552 parenthetical subexpression of a regular expression. The COUNT
2553 argument in the functions below specifies which. If COUNT is zero, you
2554 are asking about the entire match. If COUNT is positive, it specifies
2555 which subexpression you want.
2557 Recall that the subexpressions of a regular expression are those
2558 expressions grouped with escaped parentheses, `\(...\)'. The COUNTth
2559 subexpression is found by counting occurrences of `\(' from the
2560 beginning of the whole regular expression. The first subexpression is
2561 numbered 1, the second 2, and so on. Only regular expressions can have
2562 subexpressions--after a simple string search, the only information
2563 available is about the entire match.
2565 - Function: match-string count &optional in-string
2566 This function returns, as a string, the text matched in the last
2567 search or match operation. It returns the entire text if COUNT is
2568 zero, or just the portion corresponding to the COUNTth
2569 parenthetical subexpression, if COUNT is positive. If COUNT is
2570 out of range, or if that subexpression didn't match anything, the
2573 If the last such operation was done against a string with
2574 `string-match', then you should pass the same string as the
2575 argument IN-STRING. Otherwise, after a buffer search or match,
2576 you should omit IN-STRING or pass `nil' for it; but you should
2577 make sure that the current buffer when you call `match-string' is
2578 the one in which you did the searching or matching.
2580 - Function: match-beginning count
2581 This function returns the position of the start of text matched by
2582 the last regular expression searched for, or a subexpression of it.
2584 If COUNT is zero, then the value is the position of the start of
2585 the entire match. Otherwise, COUNT specifies a subexpression in
2586 the regular expression, and the value of the function is the
2587 starting position of the match for that subexpression.
2589 The value is `nil' for a subexpression inside a `\|' alternative
2590 that wasn't used in the match.
2592 - Function: match-end count
2593 This function is like `match-beginning' except that it returns the
2594 position of the end of the match, rather than the position of the
2597 Here is an example of using the match data, with a comment showing
2598 the positions within the text:
2600 (string-match "\\(qu\\)\\(ick\\)"
2601 "The quick fox jumped quickly.")
2605 (match-string 0 "The quick fox jumped quickly.")
2607 (match-string 1 "The quick fox jumped quickly.")
2609 (match-string 2 "The quick fox jumped quickly.")
2612 (match-beginning 1) ; The beginning of the match
2613 => 4 ; with `qu' is at index 4.
2615 (match-beginning 2) ; The beginning of the match
2616 => 6 ; with `ick' is at index 6.
2618 (match-end 1) ; The end of the match
2619 => 6 ; with `qu' is at index 6.
2621 (match-end 2) ; The end of the match
2622 => 9 ; with `ick' is at index 9.
2624 Here is another example. Point is initially located at the beginning
2625 of the line. Searching moves point to between the space and the word
2626 `in'. The beginning of the entire match is at the 9th character of the
2627 buffer (`T'), and the beginning of the match for the first
2628 subexpression is at the 13th character (`c').
2631 (re-search-forward "The \\(cat \\)")
2633 (match-beginning 1))
2636 ---------- Buffer: foo ----------
2637 I read "The cat -!-in the hat comes back" twice.
2640 ---------- Buffer: foo ----------
2642 (In this case, the index returned is a buffer position; the first
2643 character of the buffer counts as 1.)
2646 File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
2648 Replacing the Text That Matched
2649 -------------------------------
2651 This function replaces the text matched by the last search with
2654 - Function: replace-match replacement &optional fixedcase literal
2656 This function replaces the text in the buffer (or in STRING) that
2657 was matched by the last search. It replaces that text with
2660 If you did the last search in a buffer, you should specify `nil'
2661 for STRING. Then `replace-match' does the replacement by editing
2662 the buffer; it leaves point at the end of the replacement text,
2665 If you did the search in a string, pass the same string as STRING.
2666 Then `replace-match' does the replacement by constructing and
2667 returning a new string.
2669 If the fourth argument STRING is a string, fifth argument
2670 STRBUFFER specifies the buffer to be used for syntax-table and
2671 case-table lookup and defaults to the current buffer. When STRING
2672 is not a string, the buffer that the match occurred in has
2673 automatically been remembered and you do not need to specify it.
2675 If FIXEDCASE is non-`nil', then the case of the replacement text
2676 is not changed; otherwise, the replacement text is converted to a
2677 different case depending upon the capitalization of the text to be
2678 replaced. If the original text is all upper case, the replacement
2679 text is converted to upper case. If the first word of the
2680 original text is capitalized, then the first word of the
2681 replacement text is capitalized. If the original text contains
2682 just one word, and that word is a capital letter, `replace-match'
2683 considers this a capitalized first word rather than all upper case.
2685 If `case-replace' is `nil', then case conversion is not done,
2686 regardless of the value of FIXEDCASE. *Note Searching and Case::.
2688 If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
2689 it is, the only alterations being case changes as needed. If it
2690 is `nil' (the default), then the character `\' is treated
2691 specially. If a `\' appears in REPLACEMENT, then it must be part
2692 of one of the following sequences:
2695 `\&' stands for the entire text being replaced.
2698 `\N', where N is a digit, stands for the text that matched
2699 the Nth subexpression in the original regexp. Subexpressions
2700 are those expressions grouped inside `\(...\)'.
2703 `\\' stands for a single `\' in the replacement text.
2706 File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
2708 Accessing the Entire Match Data
2709 -------------------------------
2711 The functions `match-data' and `set-match-data' read or write the
2712 entire match data, all at once.
2714 - Function: match-data &optional integers reuse
2715 This function returns a newly constructed list containing all the
2716 information on what text the last search matched. Element zero is
2717 the position of the beginning of the match for the whole
2718 expression; element one is the position of the end of the match
2719 for the expression. The next two elements are the positions of
2720 the beginning and end of the match for the first subexpression,
2721 and so on. In general, element number 2N corresponds to
2722 `(match-beginning N)'; and element number 2N + 1 corresponds to
2725 All the elements are markers or `nil' if matching was done on a
2726 buffer, and all are integers or `nil' if matching was done on a
2727 string with `string-match'. However, if the optional first
2728 argument INTEGERS is non-`nil', always use integers (rather than
2729 markers) to represent buffer positions.
2731 If the optional second argument REUSE is a list, reuse it as part
2732 of the value. If REUSE is long enough to hold all the values, and
2733 if INTEGERS is non-`nil', no new lisp objects are created.
2735 As always, there must be no possibility of intervening searches
2736 between the call to a search function and the call to `match-data'
2737 that is intended to access the match data for that search.
2740 => (#<marker at 9 in foo>
2741 #<marker at 17 in foo>
2742 #<marker at 13 in foo>
2743 #<marker at 17 in foo>)
2745 - Function: set-match-data match-list
2746 This function sets the match data from the elements of MATCH-LIST,
2747 which should be a list that was the value of a previous call to
2750 If MATCH-LIST refers to a buffer that doesn't exist, you don't get
2751 an error; that sets the match data in a meaningless but harmless
2754 `store-match-data' is an alias for `set-match-data'.
2757 File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
2759 Saving and Restoring the Match Data
2760 -----------------------------------
2762 When you call a function that may do a search, you may need to save and
2763 restore the match data around that call, if you want to preserve the
2764 match data from an earlier search for later use. Here is an example
2765 that shows the problem that arises if you fail to save the match data:
2767 (re-search-forward "The \\(cat \\)")
2769 (foo) ; Perhaps `foo' does
2772 => 61 ; Unexpected result--not 48!
2774 You can save and restore the match data with `save-match-data':
2776 - Special Form: save-match-data body...
2777 This special form executes BODY, saving and restoring the match
2780 You can use `set-match-data' together with `match-data' to imitate
2781 the effect of the special form `save-match-data'. This is useful for
2782 writing code that can run in Emacs 18. Here is how:
2784 (let ((data (match-data)))
2786 ... ; May change the original match data.
2787 (set-match-data data)))
2789 Emacs automatically saves and restores the match data when it runs
2790 process filter functions (*note Filter Functions::) and process
2791 sentinels (*note Sentinels::).
2794 File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
2799 By default, searches in Emacs ignore the case of the text they are
2800 searching through; if you specify searching for `FOO', then `Foo' or
2801 `foo' is also considered a match. Regexps, and in particular character
2802 sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
2804 If you do not want this feature, set the variable `case-fold-search'
2805 to `nil'. Then all letters must match exactly, including case. This
2806 is a buffer-local variable; altering the variable affects only the
2807 current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you
2808 may change the value of `default-case-fold-search', which is the
2809 default value of `case-fold-search' for buffers that do not override it.
2811 Note that the user-level incremental search feature handles case
2812 distinctions differently. When given a lower case letter, it looks for
2813 a match of either case, but when given an upper case letter, it looks
2814 for an upper case letter only. But this has nothing to do with the
2815 searching functions Lisp functions use.
2817 - User Option: case-replace
2818 This variable determines whether the replacement functions should
2819 preserve case. If the variable is `nil', that means to use the
2820 replacement text verbatim. A non-`nil' value means to convert the
2821 case of the replacement text according to the text being replaced.
2823 The function `replace-match' is where this variable actually has
2824 its effect. *Note Replacing Match::.
2826 - User Option: case-fold-search
2827 This buffer-local variable determines whether searches should
2828 ignore case. If the variable is `nil' they do not ignore case;
2829 otherwise they do ignore case.
2831 - Variable: default-case-fold-search
2832 The value of this variable is the default value for
2833 `case-fold-search' in buffers that do not override it. This is the
2834 same as `(default-value 'case-fold-search)'.
2837 File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching
2839 Standard Regular Expressions Used in Editing
2840 ============================================
2842 This section describes some variables that hold regular expressions
2843 used for certain purposes in editing:
2845 - Variable: page-delimiter
2846 This is the regexp describing line-beginnings that separate pages.
2847 The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
2848 matches a line that starts with a formfeed character.
2850 The following two regular expressions should _not_ assume the match
2851 always starts at the beginning of a line; they should not use `^' to
2852 anchor the match. Most often, the paragraph commands do check for a
2853 match only at the beginning of a line, which means that `^' would be
2854 superfluous. When there is a nonzero left margin, they accept matches
2855 that start after the left margin. In that case, a `^' would be
2856 incorrect. However, a `^' is harmless in modes where a left margin is
2859 - Variable: paragraph-separate
2860 This is the regular expression for recognizing the beginning of a
2861 line that separates paragraphs. (If you change this, you may have
2862 to change `paragraph-start' also.) The default value is
2863 `"[ \t\f]*$"', which matches a line that consists entirely of
2864 spaces, tabs, and form feeds (after its left margin).
2866 - Variable: paragraph-start
2867 This is the regular expression for recognizing the beginning of a
2868 line that starts _or_ separates paragraphs. The default value is
2869 `"[ \t\n\f]"', which matches a line starting with a space, tab,
2870 newline, or form feed (after its left margin).
2872 - Variable: sentence-end
2873 This is the regular expression describing the end of a sentence.
2874 (All paragraph boundaries also end sentences, regardless.) The
2877 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
2879 This means a period, question mark or exclamation mark, followed
2880 optionally by a closing parenthetical character, followed by tabs,
2881 spaces or new lines.
2883 For a detailed explanation of this regular expression, see *Note
2887 File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
2892 A "syntax table" specifies the syntactic textual function of each
2893 character. This information is used by the parsing commands, the
2894 complex movement commands, and others to determine where words, symbols,
2895 and other syntactic constructs begin and end. The current syntax table
2896 controls the meaning of the word motion functions (*note Word Motion::)
2897 and the list motion functions (*note List Motion::) as well as the
2898 functions in this chapter.
2902 * Basics: Syntax Basics. Basic concepts of syntax tables.
2903 * Desc: Syntax Descriptors. How characters are classified.
2904 * Syntax Table Functions:: How to create, examine and alter syntax tables.
2905 * Motion and Syntax:: Moving over characters with certain syntaxes.
2906 * Parsing Expressions:: Parsing balanced expressions
2907 using the syntax table.
2908 * Standard Syntax Tables:: Syntax tables used by various major modes.
2909 * Syntax Table Internals:: How syntax table information is stored.
2912 File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables
2914 Syntax Table Concepts
2915 =====================
2917 A "syntax table" provides Emacs with the information that determines
2918 the syntactic use of each character in a buffer. This information is
2919 used by the parsing commands, the complex movement commands, and others
2920 to determine where words, symbols, and other syntactic constructs begin
2921 and end. The current syntax table controls the meaning of the word
2922 motion functions (*note Word Motion::) and the list motion functions
2923 (*note List Motion::) as well as the functions in this chapter.
2925 Under XEmacs 20 and later, a syntax table is a particular subtype of the
2926 primitive char table type (*note Char Tables::), and each element of the
2927 char table is an integer that encodes the syntax of the character in
2928 question, or a cons of such an integer and a matching character (for
2929 characters with parenthesis syntax).
2931 Under XEmacs 19, a syntax table is a vector of 256 elements; it
2932 contains one entry for each of the 256 possible characters in an 8-bit
2933 byte. Each element is an integer that encodes the syntax of the
2934 character in question. (The matching character, if any, is embedded in
2935 the bits of this integer.)
2937 Syntax tables are used only for moving across text, not for the Emacs
2938 Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading
2939 Lisp expressions, and these rules cannot be changed.
2941 Each buffer has its own major mode, and each major mode has its own
2942 idea of the syntactic class of various characters. For example, in Lisp
2943 mode, the character `;' begins a comment, but in C mode, it terminates
2944 a statement. To support these variations, XEmacs makes the choice of
2945 syntax table local to each buffer. Typically, each major mode has its
2946 own syntax table and installs that table in each buffer that uses that
2947 mode. Changing this table alters the syntax in all those buffers as
2948 well as in any buffers subsequently put in that mode. Occasionally
2949 several similar modes share one syntax table. *Note Example Major
2950 Modes::, for an example of how to set up a syntax table.
2952 A syntax table can inherit the data for some characters from the
2953 standard syntax table, while specifying other characters itself. The
2954 "inherit" syntax class means "inherit this character's syntax from the
2955 standard syntax table." Most major modes' syntax tables inherit the
2956 syntax of character codes 0 through 31 and 128 through 255. This is
2957 useful with character sets such as ISO Latin-1 that have additional
2958 alphabetic characters in the range 128 to 255. Just changing the
2959 standard syntax for these characters affects all major modes.
2961 - Function: syntax-table-p object
2962 This function returns `t' if OBJECT is a vector of length 256
2963 elements. This means that the vector may be a syntax table.
2964 However, according to this test, any vector of length 256 is
2965 considered to be a syntax table, no matter what its contents.
2968 File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables
2973 This section describes the syntax classes and flags that denote the
2974 syntax of a character, and how they are represented as a "syntax
2975 descriptor", which is a Lisp string that you pass to
2976 `modify-syntax-entry' to specify the desired syntax.
2978 XEmacs defines a number of "syntax classes". Each syntax table puts
2979 each character into one class. There is no necessary relationship
2980 between the class of a character in one syntax table and its class in
2983 Each class is designated by a mnemonic character, which serves as the
2984 name of the class when you need to specify a class. Usually the
2985 designator character is one that is frequently in that class; however,
2986 its meaning as a designator is unvarying and independent of what syntax
2987 that character currently has.
2989 A syntax descriptor is a Lisp string that specifies a syntax class, a
2990 matching character (used only for the parenthesis classes) and flags.
2991 The first character is the designator for a syntax class. The second
2992 character is the character to match; if it is unused, put a space there.
2993 Then come the characters for any desired flags. If no matching
2994 character or flags are needed, one character is sufficient.
2996 For example, the descriptor for the character `*' in C mode is
2997 `. 23' (i.e., punctuation, matching character slot unused, second
2998 character of a comment-starter, first character of an comment-ender),
2999 and the entry for `/' is `. 14' (i.e., punctuation, matching character
3000 slot unused, first character of a comment-starter, second character of
3005 * Syntax Class Table:: Table of syntax classes.
3006 * Syntax Flags:: Additional flags each character can have.
3009 File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors
3011 Table of Syntax Classes
3012 -----------------------
3014 Here is a table of syntax classes, the characters that stand for them,
3015 their meanings, and examples of their use.
3017 - Syntax class: whitespace character
3018 "Whitespace characters" (designated with `-') separate symbols and
3019 words from each other. Typically, whitespace characters have no
3020 other syntactic significance, and multiple whitespace characters
3021 are syntactically equivalent to a single one. Space, tab, newline
3022 and formfeed are almost always classified as whitespace. (The
3023 designator ` ' is accepted for backwards compatibility with older
3024 versions of XEmacs, but is deprecated. It is invalid in GNU
3027 - Syntax class: word constituent
3028 "Word constituents" (designated with `w') are parts of normal
3029 English words and are typically used in variable and command names
3030 in programs. All upper- and lower-case letters, and the digits,
3031 are typically word constituents.
3033 - Syntax class: symbol constituent
3034 "Symbol constituents" (designated with `_') are the extra
3035 characters that are used in variable and command names along with
3036 word constituents. For example, the symbol constituents class is
3037 used in Lisp mode to indicate that certain characters may be part
3038 of symbol names even though they are not part of English words.
3039 These characters are `$&*+-_<>'. In standard C, the only
3040 non-word-constituent character that is valid in symbols is
3043 - Syntax class: punctuation character
3044 "Punctuation characters" (`.') are those characters that are used
3045 as punctuation in English, or are used in some way in a programming
3046 language to separate symbols from one another. Most programming
3047 language modes, including Emacs Lisp mode, have no characters in
3048 this class since the few characters that are not symbol or word
3049 constituents all have other uses.
3051 - Syntax class: open parenthesis character
3052 - Syntax class: close parenthesis character
3053 Open and close "parenthesis characters" are characters used in
3054 dissimilar pairs to surround sentences or expressions. Such a
3055 grouping is begun with an open parenthesis character and
3056 terminated with a close. Each open parenthesis character matches
3057 a particular close parenthesis character, and vice versa.
3058 Normally, XEmacs indicates momentarily the matching open
3059 parenthesis when you insert a close parenthesis. *Note Blinking::.
3061 The class of open parentheses is designated with `(', and that of
3062 close parentheses with `)'.
3064 In English text, and in C code, the parenthesis pairs are `()',
3065 `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and
3066 vectors (`()' and `[]') are classified as parenthesis characters.
3068 - Syntax class: string quote
3069 "String quote characters" (designated with `"') are used in many
3070 languages, including Lisp and C, to delimit string constants. The
3071 same string quote character appears at the beginning and the end
3072 of a string. Such quoted strings do not nest.
3074 The parsing facilities of XEmacs consider a string as a single
3075 token. The usual syntactic meanings of the characters in the
3076 string are suppressed.
3078 The Lisp modes have two string quote characters: double-quote (`"')
3079 and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is
3080 used in Common Lisp. C also has two string quote characters:
3081 double-quote for strings, and single-quote (`'') for character
3084 English text has no string quote characters because English is not
3085 a programming language. Although quotation marks are used in
3086 English, we do not want them to turn off the usual syntactic
3087 properties of other characters in the quotation.
3089 - Syntax class: escape
3090 An "escape character" (designated with `\') starts an escape
3091 sequence such as is used in C string and character constants. The
3092 character `\' belongs to this class in both C and Lisp. (In C, it
3093 is used thus only inside strings, but it turns out to cause no
3094 trouble to treat it this way throughout C code.)
3096 Characters in this class count as part of words if
3097 `words-include-escapes' is non-`nil'. *Note Word Motion::.
3099 - Syntax class: character quote
3100 A "character quote character" (designated with `/') quotes the
3101 following character so that it loses its normal syntactic meaning.
3102 This differs from an escape character in that only the character
3103 immediately following is ever affected.
3105 Characters in this class count as part of words if
3106 `words-include-escapes' is non-`nil'. *Note Word Motion::.
3108 This class is used for backslash in TeX mode.
3110 - Syntax class: paired delimiter
3111 "Paired delimiter characters" (designated with `$') are like
3112 string quote characters except that the syntactic properties of the
3113 characters between the delimiters are not suppressed. Only TeX
3114 mode uses a paired delimiter presently--the `$' that both enters
3115 and leaves math mode.
3117 - Syntax class: expression prefix
3118 An "expression prefix operator" (designated with `'') is used for
3119 syntactic operators that are part of an expression if they appear
3120 next to one. These characters in Lisp include the apostrophe, `''
3121 (used for quoting), the comma, `,' (used in macros), and `#' (used
3122 in the read syntax for certain data types).
3124 - Syntax class: comment starter
3125 - Syntax class: comment ender
3126 The "comment starter" and "comment ender" characters are used in
3127 various languages to delimit comments. These classes are
3128 designated with `<' and `>', respectively.
3130 English text has no comment characters. In Lisp, the semicolon
3131 (`;') starts a comment and a newline or formfeed ends one.
3133 - Syntax class: inherit
3134 This syntax class does not specify a syntax. It says to look in
3135 the standard syntax table to find the syntax of this character.
3136 The designator for this syntax code is `@'.
3139 File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors
3144 In addition to the classes, entries for characters in a syntax table
3145 can include flags. There are eleven possible flags, represented by the
3146 digits `1'-`8', and the lowercase letters `a', `b', and `p'.
3148 All the flags except `p' are used to describe comment delimiters.
3149 The digit flags indicate that a character can _also_ be part of a
3150 multi-character comment sequence, in addition to the syntactic
3151 properties associated with its character class. The flags must be
3152 independent of the class and each other for the sake of characters such
3153 as `*' in C mode, which is a punctuation character, _and_ the second
3154 character of a start-of-comment sequence (`/*'), _and_ the first
3155 character of an end-of-comment sequence (`*/').
3157 Emacs supports two comment styles simultaneously in any one syntax
3158 table. This is for the sake of C++. Each style of comment syntax has
3159 its own comment-start sequence and its own comment-end sequence. Each
3160 comment must stick to one style or the other; thus, if it starts with
3161 the comment-start sequence of style "b", it must also end with the
3162 comment-end sequence of style "b".
3164 As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary
3165 comment-start sequences and two arbitrary comment-end sequences. (Thus
3166 the need for 8 flags.) GNU Emacs restricts the comment-start sequences
3167 to start with the same character, XEmacs does not. This means that for
3168 two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses
3169 the digit flags `5'-`8'.
3171 A one character comment-end sequence applies to the "b" style if its
3172 first character has the `b' flag set; otherwise, it applies to the "a"
3173 style. The `a' flag is optional. These flags have no effect on
3174 non-comment characters; two-character styles are determined by the
3177 The flags for a character C are:
3179 * `1' means C is the start of a two-character comment-start sequence
3182 * `2' means C is the second character of such a sequence.
3184 * `3' means C is the start of a two-character comment-end sequence
3187 * `4' means C is the second character of such a sequence.
3189 * `5' means C is the start of a two-character comment-start sequence
3192 * `6' means C is the second character of such a sequence.
3194 * `7' means C is the start of a two-character comment-end sequence
3197 * `8' means C is the second character of such a sequence.
3199 * `a' means that C as a comment delimiter belongs to the default "a"
3200 comment style. (This flag is optional.)
3202 * `b' means that C as a comment delimiter belongs to the alternate
3205 * `p' identifies an additional "prefix character" for Lisp syntax.
3206 These characters are treated as whitespace when they appear between
3207 expressions. When they appear within an expression, they are
3208 handled according to their usual syntax codes.
3210 The function `backward-prefix-chars' moves back over these
3211 characters, as well as over characters whose primary syntax class
3212 is prefix (`''). *Note Motion and Syntax::.
3214 Lisp (as you would expect) has a simple comment syntax.
3222 Note that no flags are used. This defines two comment-delimiting
3226 This is a single-character comment-start sequence because the
3227 syntax class is `<'.
3230 This is a single character comment-end sequence because the syntax
3231 class is `>' and the `b' flag is not set.
3233 C++ (again, as you would expect) has a baroque, overrich, and
3234 excessively complex comment syntax.
3245 Note that the "b" style mixes one-character and two-character
3246 sequences. The table above defines four comment-delimiting sequences:
3249 This is a comment-start sequence for "a" style because the `1'
3250 flag is set on `/' and the `2' flag is set on `*'.
3253 This is a comment-start sequence for "b" style because both the `5'
3254 and the `6' flags are set on `/'.
3257 This is a comment-end sequence for "a" style because the `3' flag
3258 is set on `*' and the `4' flag is set on `/'.
3261 This is a comment-end sequence for "b" style, because the newline
3262 character has the `b' flag.
3265 File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables
3267 Syntax Table Functions
3268 ======================
3270 In this section we describe functions for creating, accessing and
3271 altering syntax tables.
3273 - Function: make-syntax-table &optional oldtable
3274 This function creates a new syntax table. Character codes 0
3275 through 31 and 128 through 255 are set up to inherit from the
3276 standard syntax table. The other character codes are set up by
3277 copying what the standard syntax table says about them.
3279 Most major mode syntax tables are created in this way.
3281 - Function: copy-syntax-table &optional syntax-table
3282 This function constructs a copy of SYNTAX-TABLE and returns it.
3283 If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy
3284 of the current syntax table. Otherwise, an error is signaled if
3285 SYNTAX-TABLE is not a syntax table.
3287 - Command: modify-syntax-entry char-range syntax-descriptor &optional
3289 This function sets the syntax entry for CHAR-RANGE according to
3290 SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a
3291 range of characters, as used with `put-char-table'. The syntax is
3292 changed only for SYNTAX-TABLE, which defaults to the current
3293 buffer's syntax table, and not in any other syntax table. The
3294 argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a
3295 string beginning with a class designator character, and optionally
3296 containing a matching character and flags as well. *Note Syntax
3299 This function always returns `nil'. The old syntax information in
3300 the table for CHAR-RANGE is discarded.
3302 An error is signaled if the first character of the syntax
3303 descriptor is not one of the twelve syntax class designator
3308 ;; Put the space character in class whitespace.
3309 (modify-syntax-entry ?\ " ")
3312 ;; Make `$' an open parenthesis character,
3313 ;; with `^' as its matching close.
3314 (modify-syntax-entry ?$ "(^")
3317 ;; Make `^' a close parenthesis character,
3318 ;; with `$' as its matching open.
3319 (modify-syntax-entry ?^ ")$")
3322 ;; Make `/' a punctuation character,
3323 ;; the first character of a start-comment sequence,
3324 ;; and the second character of an end-comment sequence.
3325 ;; This is used in C mode.
3326 (modify-syntax-entry ?/ ". 14")
3329 - Function: char-syntax character &optional syntax-table
3330 This function returns the syntax class of CHARACTER, represented
3331 by its mnemonic designator character. This _only_ returns the
3332 class, not any matching parenthesis or flags.
3334 An error is signaled if CHARACTER is not a character.
3336 The characters that correspond to various syntax codes are listed
3337 in the documentation of `modify-syntax-entry'.
3339 Optional second argument SYNTAX-TABLE is the syntax table to be
3340 used, and defaults to the current buffer's syntax table.
3342 The following examples apply to C mode. The first example shows
3343 that the syntax class of space is whitespace (represented by a
3344 space). The second example shows that the syntax of `/' is
3345 punctuation. This does not show the fact that it is also part of
3346 comment-start and -end sequences. The third example shows that
3347 open parenthesis is in the class of open parentheses. This does
3348 not show the fact that it has a matching character, `)'.
3350 (char-to-string (char-syntax ?\ ))
3353 (char-to-string (char-syntax ?/))
3356 (char-to-string (char-syntax ?\())
3359 - Function: set-syntax-table syntax-table &optional buffer
3360 This function makes SYNTAX-TABLE the syntax table for BUFFER, which
3361 defaults to the current buffer if omitted. It returns
3364 - Function: syntax-table &optional buffer
3365 This function returns the syntax table for BUFFER, which defaults
3366 to the current buffer if omitted.
3369 File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables
3374 This section describes functions for moving across characters in
3375 certain syntax classes. None of these functions exists in Emacs
3376 version 18 or earlier.
3378 - Function: skip-syntax-forward syntaxes &optional limit buffer
3379 This function moves point forward across characters having syntax
3380 classes mentioned in SYNTAXES. It stops when it encounters the
3381 end of the buffer, or position LIMIT (if specified), or a
3382 character it is not supposed to skip. Optional argument BUFFER
3383 defaults to the current buffer if omitted.
3385 - Function: skip-syntax-backward syntaxes &optional limit buffer
3386 This function moves point backward across characters whose syntax
3387 classes are mentioned in SYNTAXES. It stops when it encounters
3388 the beginning of the buffer, or position LIMIT (if specified), or a
3389 character it is not supposed to skip. Optional argument BUFFER
3390 defaults to the current buffer if omitted.
3393 - Function: backward-prefix-chars &optional buffer
3394 This function moves point backward over any number of characters
3395 with expression prefix syntax. This includes both characters in
3396 the expression prefix syntax class, and characters with the `p'
3397 flag. Optional argument BUFFER defaults to the current buffer if
3401 File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
3403 Parsing Balanced Expressions
3404 ============================
3406 Here are several functions for parsing and scanning balanced
3407 expressions, also known as "sexps", in which parentheses match in
3408 pairs. The syntax table controls the interpretation of characters, so
3409 these functions can be used for Lisp expressions when in Lisp mode and
3410 for C expressions when in C mode. *Note List Motion::, for convenient
3411 higher-level functions for moving over balanced expressions.
3413 - Function: parse-partial-sexp start limit &optional target-depth
3414 stop-before state stop-comment buffer
3415 This function parses a sexp in the current buffer starting at
3416 START, not scanning past LIMIT. It stops at position LIMIT or
3417 when certain criteria described below are met, and sets point to
3418 the location where parsing stops. It returns a value describing
3419 the status of the parse at the point where it stops.
3421 If STATE is `nil', START is assumed to be at the top level of
3422 parenthesis structure, such as the beginning of a function
3423 definition. Alternatively, you might wish to resume parsing in the
3424 middle of the structure. To do this, you must provide a STATE
3425 argument that describes the initial status of parsing.
3427 If the third argument TARGET-DEPTH is non-`nil', parsing stops if
3428 the depth in parentheses becomes equal to TARGET-DEPTH. The depth
3429 starts at 0, or at whatever is given in STATE.
3431 If the fourth argument STOP-BEFORE is non-`nil', parsing stops
3432 when it comes to any character that starts a sexp. If
3433 STOP-COMMENT is non-`nil', parsing stops when it comes to the
3436 The fifth argument STATE is an eight-element list of the same form
3437 as the value of this function, described below. The return value
3438 of one call may be used to initialize the state of the parse on
3439 another call to `parse-partial-sexp'.
3441 The result is a list of eight elements describing the final state
3444 0. The depth in parentheses, counting from 0.
3446 1. The character position of the start of the innermost
3447 parenthetical grouping containing the stopping point; `nil'
3450 2. The character position of the start of the last complete
3451 subexpression terminated; `nil' if none.
3453 3. Non-`nil' if inside a string. More precisely, this is the
3454 character that will terminate the string.
3456 4. `t' if inside a comment (of either style).
3458 5. `t' if point is just after a quote character.
3460 6. The minimum parenthesis depth encountered during this scan.
3462 7. `t' if inside a comment of style "b".
3464 Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
3466 This function is most often used to compute indentation for
3467 languages that have nested parentheses.
3469 - Function: scan-lists from count depth &optional buffer noerror
3470 This function scans forward COUNT balanced parenthetical groupings
3471 from character number FROM. It returns the character position
3472 where the scan stops.
3474 If DEPTH is nonzero, parenthesis depth counting begins from that
3475 value. The only candidates for stopping are places where the
3476 depth in parentheses becomes zero; `scan-lists' counts COUNT such
3477 places and then stops. Thus, a positive value for DEPTH means go
3478 out DEPTH levels of parenthesis.
3480 Scanning ignores comments if `parse-sexp-ignore-comments' is
3483 If the scan reaches the beginning or end of the buffer (or its
3484 accessible portion), and the depth is not zero, an error is
3485 signaled. If the depth is zero but the count is not used up,
3488 If optional arg BUFFER is non-`nil', scanning occurs in that
3489 buffer instead of in the current buffer.
3491 If optional arg NOERROR is non-`nil', `scan-lists' will return
3492 `nil' instead of signalling an error.
3494 - Function: scan-sexps from count &optional buffer noerror
3495 This function scans forward COUNT sexps from character position
3496 FROM. It returns the character position where the scan stops.
3498 Scanning ignores comments if `parse-sexp-ignore-comments' is
3501 If the scan reaches the beginning or end of (the accessible part
3502 of) the buffer in the middle of a parenthetical grouping, an error
3503 is signaled. If it reaches the beginning or end between groupings
3504 but before count is used up, `nil' is returned.
3506 If optional arg BUFFER is non-`nil', scanning occurs in that
3507 buffer instead of in the current buffer.
3509 If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
3510 instead of signalling an error.
3512 - Variable: parse-sexp-ignore-comments
3513 If the value is non-`nil', then comments are treated as whitespace
3514 by the functions in this section and by `forward-sexp'.
3516 In older Emacs versions, this feature worked only when the comment
3517 terminator is something like `*/', and appears only to end a
3518 comment. In languages where newlines terminate comments, it was
3519 necessary make this variable `nil', since not every newline is the
3520 end of a comment. This limitation no longer exists.
3522 You can use `forward-comment' to move forward or backward over one
3523 comment or several comments.
3525 - Function: forward-comment &optional count buffer
3526 This function moves point forward across COUNT comments (backward,
3527 if COUNT is negative). If it finds anything other than a comment
3528 or whitespace, it stops, leaving point at the place where it
3529 stopped. It also stops after satisfying COUNT. COUNT defaults to
3532 Optional argument BUFFER defaults to the current buffer.
3534 To move forward over all comments and whitespace following point, use
3535 `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
3536 to use, because the number of comments in the buffer cannot exceed that
3540 File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
3542 Some Standard Syntax Tables
3543 ===========================
3545 Most of the major modes in XEmacs have their own syntax tables. Here
3546 are several of them:
3548 - Function: standard-syntax-table
3549 This function returns the standard syntax table, which is the
3550 syntax table used in Fundamental mode.
3552 - Variable: text-mode-syntax-table
3553 The value of this variable is the syntax table used in Text mode.
3555 - Variable: c-mode-syntax-table
3556 The value of this variable is the syntax table for C-mode buffers.
3558 - Variable: emacs-lisp-mode-syntax-table
3559 The value of this variable is the syntax table used in Emacs Lisp
3560 mode by editing commands. (It has no effect on the Lisp `read'
3564 File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
3566 Syntax Table Internals
3567 ======================
3569 Each element of a syntax table is an integer that encodes the syntax of
3570 one character: the syntax class, possible matching character, and
3571 flags. Lisp programs don't usually work with the elements directly; the
3572 Lisp-level syntax table functions usually work with syntax descriptors
3573 (*note Syntax Descriptors::).
3575 The low 8 bits of each element of a syntax table indicate the syntax
3623 The next 8 bits are the matching opposite parenthesis (if the
3624 character has parenthesis syntax); otherwise, they are not meaningful.
3625 The next 6 bits are the flags.
3628 File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
3630 Abbrevs And Abbrev Expansion
3631 ****************************
3633 An abbreviation or "abbrev" is a string of characters that may be
3634 expanded to a longer string. The user can insert the abbrev string and
3635 find it replaced automatically with the expansion of the abbrev. This
3638 The set of abbrevs currently in effect is recorded in an "abbrev
3639 table". Each buffer has a local abbrev table, but normally all buffers
3640 in the same major mode share one abbrev table. There is also a global
3641 abbrev table. Normally both are used.
3643 An abbrev table is represented as an obarray containing a symbol for
3644 each abbreviation. The symbol's name is the abbreviation; its value is
3645 the expansion; its function definition is the hook function to do the
3646 expansion (*note Defining Abbrevs::); its property list cell contains
3647 the use count, the number of times the abbreviation has been expanded.
3648 Because these symbols are not interned in the usual obarray, they will
3649 never appear as the result of reading a Lisp expression; in fact,
3650 normally they are never used except by the code that handles abbrevs.
3651 Therefore, it is safe to use them in an extremely nonstandard way.
3652 *Note Creating Symbols::.
3654 For the user-level commands for abbrevs, see *Note Abbrev Mode:
3659 * Abbrev Mode:: Setting up XEmacs for abbreviation.
3660 * Tables: Abbrev Tables. Creating and working with abbrev tables.
3661 * Defining Abbrevs:: Specifying abbreviations and their expansions.
3662 * Files: Abbrev Files. Saving abbrevs in files.
3663 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
3664 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
3667 File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
3669 Setting Up Abbrev Mode
3670 ======================
3672 Abbrev mode is a minor mode controlled by the value of the variable
3675 - Variable: abbrev-mode
3676 A non-`nil' value of this variable turns on the automatic expansion
3677 of abbrevs when their abbreviations are inserted into a buffer.
3678 If the value is `nil', abbrevs may be defined, but they are not
3679 expanded automatically.
3681 This variable automatically becomes local when set in any fashion.
3683 - Variable: default-abbrev-mode
3684 This is the value of `abbrev-mode' for buffers that do not
3685 override it. This is the same as `(default-value 'abbrev-mode)'.
3688 File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
3693 This section describes how to create and manipulate abbrev tables.
3695 - Function: make-abbrev-table
3696 This function creates and returns a new, empty abbrev table--an
3697 obarray containing no symbols. It is a vector filled with zeros.
3699 - Function: clear-abbrev-table table
3700 This function undefines all the abbrevs in abbrev table TABLE,
3701 leaving it empty. The function returns `nil'.
3703 - Function: define-abbrev-table table-name definitions
3704 This function defines TABLE-NAME (a symbol) as an abbrev table
3705 name, i.e., as a variable whose value is an abbrev table. It
3706 defines abbrevs in the table according to DEFINITIONS, a list of
3707 elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The
3708 value is always `nil'.
3710 - Variable: abbrev-table-name-list
3711 This is a list of symbols whose values are abbrev tables.
3712 `define-abbrev-table' adds the new abbrev table name to this list.
3714 - Function: insert-abbrev-table-description name &optional human
3715 This function inserts before point a description of the abbrev
3716 table named NAME. The argument NAME is a symbol whose value is an
3717 abbrev table. The value is always `nil'.
3719 If HUMAN is non-`nil', the description is human-oriented.
3720 Otherwise the description is a Lisp expression--a call to
3721 `define-abbrev-table' that would define NAME exactly as it is
3725 File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
3730 These functions define an abbrev in a specified abbrev table.
3731 `define-abbrev' is the low-level basic function, while `add-abbrev' is
3732 used by commands that ask for information from the user.
3734 - Function: add-abbrev table type arg
3735 This function adds an abbreviation to abbrev table TABLE based on
3736 information from the user. The argument TYPE is a string
3737 describing in English the kind of abbrev this will be (typically,
3738 `"global"' or `"mode-specific"'); this is used in prompting the
3739 user. The argument ARG is the number of words in the expansion.
3741 The return value is the symbol that internally represents the new
3742 abbrev, or `nil' if the user declines to confirm redefining an
3745 - Function: define-abbrev table name &optional expansion hook count
3746 This function defines an abbrev in TABLE named NAME, to expand to
3747 EXPANSION, and call HOOK. The return value is an uninterned
3748 symbol that represents the abbrev inside XEmacs; its name is NAME.
3750 The argument NAME should be a string. The argument EXPANSION
3751 should be a string, or `nil' to undefine the abbrev.
3753 The argument HOOK is a function or `nil'. If HOOK is non-`nil',
3754 then it is called with no arguments after the abbrev is replaced
3755 with EXPANSION; point is located at the end of EXPANSION when HOOK
3758 The use count of the abbrev is initialized to zero.
3760 - User Option: only-global-abbrevs
3761 If this variable is non-`nil', it means that the user plans to use
3762 global abbrevs only. This tells the commands that define
3763 mode-specific abbrevs to define global ones instead. This
3764 variable does not alter the behavior of the functions in this
3765 section; it is examined by their callers.
3768 File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
3770 Saving Abbrevs in Files
3771 =======================
3773 A file of saved abbrev definitions is actually a file of Lisp code.
3774 The abbrevs are saved in the form of a Lisp program to define the same
3775 abbrev tables with the same contents. Therefore, you can load the file
3776 with `load' (*note How Programs Do Loading::). However, the function
3777 `quietly-read-abbrev-file' is provided as a more convenient interface.
3779 User-level facilities such as `save-some-buffers' can save abbrevs
3780 in a file automatically, under the control of variables described here.
3782 - User Option: abbrev-file-name
3783 This is the default file name for reading and saving abbrevs.
3785 - Function: quietly-read-abbrev-file &optional filename
3786 This function reads abbrev definitions from a file named FILENAME,
3787 previously written with `write-abbrev-file'. If FILENAME is
3788 `nil', the file specified in `abbrev-file-name' is used.
3789 `save-abbrevs' is set to `t' so that changes will be saved.
3791 This function does not display any messages. It returns `nil'.
3793 - User Option: save-abbrevs
3794 A non-`nil' value for `save-abbrev' means that XEmacs should save
3795 abbrevs when files are saved. `abbrev-file-name' specifies the
3796 file to save the abbrevs in.
3798 - Variable: abbrevs-changed
3799 This variable is set non-`nil' by defining or altering any
3800 abbrevs. This serves as a flag for various XEmacs commands to
3801 offer to save your abbrevs.
3803 - Command: write-abbrev-file filename
3804 Save all abbrev definitions, in all abbrev tables, in the file
3805 FILENAME, in the form of a Lisp program that when loaded will
3806 define the same abbrevs. This function returns `nil'.
3809 File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
3811 Looking Up and Expanding Abbreviations
3812 ======================================
3814 Abbrevs are usually expanded by commands for interactive use, including
3815 `self-insert-command'. This section describes the subroutines used in
3816 writing such functions, as well as the variables they use for
3819 - Function: abbrev-symbol abbrev &optional table
3820 This function returns the symbol representing the abbrev named
3821 ABBREV. The value returned is `nil' if that abbrev is not
3822 defined. The optional second argument TABLE is the abbrev table
3823 to look it up in. If TABLE is `nil', this function tries first
3824 the current buffer's local abbrev table, and second the global
3827 - Function: abbrev-expansion abbrev &optional table
3828 This function returns the string that ABBREV would expand into (as
3829 defined by the abbrev tables used for the current buffer). The
3830 optional argument TABLE specifies the abbrev table to use, as in
3833 - Command: expand-abbrev
3834 This command expands the abbrev before point, if any. If point
3835 does not follow an abbrev, this command does nothing. The command
3836 returns `t' if it did expansion, `nil' otherwise.
3838 - Command: abbrev-prefix-mark &optional arg
3839 Mark current point as the beginning of an abbrev. The next call to
3840 `expand-abbrev' will use the text from here to point (where it is
3841 then) as the abbrev to expand, rather than using the previous word
3844 - User Option: abbrev-all-caps
3845 When this is set non-`nil', an abbrev entered entirely in upper
3846 case is expanded using all upper case. Otherwise, an abbrev
3847 entered entirely in upper case is expanded by capitalizing each
3848 word of the expansion.
3850 - Variable: abbrev-start-location
3851 This is the buffer position for `expand-abbrev' to use as the start
3852 of the next abbrev to be expanded. (`nil' means use the word
3853 before point instead.) `abbrev-start-location' is set to `nil'
3854 each time `expand-abbrev' is called. This variable is also set by
3855 `abbrev-prefix-mark'.
3857 - Variable: abbrev-start-location-buffer
3858 The value of this variable is the buffer for which
3859 `abbrev-start-location' has been set. Trying to expand an abbrev
3860 in any other buffer clears `abbrev-start-location'. This variable
3861 is set by `abbrev-prefix-mark'.
3863 - Variable: last-abbrev
3864 This is the `abbrev-symbol' of the last abbrev expanded. This
3865 information is left by `expand-abbrev' for the sake of the
3866 `unexpand-abbrev' command.
3868 - Variable: last-abbrev-location
3869 This is the location of the last abbrev expanded. This contains
3870 information left by `expand-abbrev' for the sake of the
3871 `unexpand-abbrev' command.
3873 - Variable: last-abbrev-text
3874 This is the exact expansion text of the last abbrev expanded,
3875 after case conversion (if any). Its value is `nil' if the abbrev
3876 has already been unexpanded. This contains information left by
3877 `expand-abbrev' for the sake of the `unexpand-abbrev' command.
3879 - Variable: pre-abbrev-expand-hook
3880 This is a normal hook whose functions are executed, in sequence,
3881 just before any expansion of an abbrev. *Note Hooks::. Since it
3882 is a normal hook, the hook functions receive no arguments.
3883 However, they can find the abbrev to be expanded by looking in the
3884 buffer before point.
3886 The following sample code shows a simple use of
3887 `pre-abbrev-expand-hook'. If the user terminates an abbrev with a
3888 punctuation character, the hook function asks for confirmation. Thus,
3889 this hook allows the user to decide whether to expand the abbrev, and
3890 aborts expansion if it is not confirmed.
3892 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
3894 ;; This is the function invoked by `pre-abbrev-expand-hook'.
3896 ;; If the user terminated the abbrev with a space, the function does
3897 ;; nothing (that is, it returns so that the abbrev can expand). If the
3898 ;; user entered some other character, this function asks whether
3899 ;; expansion should continue.
3901 ;; If the user answers the prompt with `y', the function returns
3902 ;; `nil' (because of the `not' function), but that is
3903 ;; acceptable; the return value has no effect on expansion.
3905 (defun query-if-not-space ()
3906 (if (/= ?\ (preceding-char))
3907 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
3908 (error "Not expanding this abbrev"))))
3911 File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
3913 Standard Abbrev Tables
3914 ======================
3916 Here we list the variables that hold the abbrev tables for the
3917 preloaded major modes of XEmacs.
3919 - Variable: global-abbrev-table
3920 This is the abbrev table for mode-independent abbrevs. The abbrevs
3921 defined in it apply to all buffers. Each buffer may also have a
3922 local abbrev table, whose abbrev definitions take precedence over
3923 those in the global table.
3925 - Variable: local-abbrev-table
3926 The value of this buffer-local variable is the (mode-specific)
3927 abbreviation table of the current buffer.
3929 - Variable: fundamental-mode-abbrev-table
3930 This is the local abbrev table used in Fundamental mode; in other
3931 words, it is the local abbrev table in all buffers in Fundamental
3934 - Variable: text-mode-abbrev-table
3935 This is the local abbrev table used in Text mode.
3937 - Variable: c-mode-abbrev-table
3938 This is the local abbrev table used in C mode.
3940 - Variable: lisp-mode-abbrev-table
3941 This is the local abbrev table used in Lisp mode and Emacs Lisp
3945 File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
3950 An "extent" is a region of text (a start position and an end position)
3951 that is displayed in a particular face and can have certain other
3952 properties such as being read-only. Extents can overlap each other.
3953 XEmacs efficiently handles buffers with large numbers of extents in
3956 - Function: extentp object
3957 This returns `t' if OBJECT is an extent.
3961 * Intro to Extents:: Extents are regions over a buffer or string.
3962 * Creating and Modifying Extents::
3963 Basic extent functions.
3964 * Extent Endpoints:: Accessing and setting the bounds of an extent.
3965 * Finding Extents:: Determining which extents are in an object.
3966 * Mapping Over Extents:: More sophisticated functions for extent scanning.
3967 * Extent Properties:: Extents have built-in and user-definable properties.
3968 * Detached Extents:: Extents that are not in a buffer.
3969 * Extent Parents:: Inheriting properties from another extent.
3970 * Duplicable Extents:: Extents can be marked to be copied into strings.
3971 * Extents and Events:: Extents can interact with the keyboard and mouse.
3972 * Atomic Extents:: Treating a block of text as a single entity.
3975 File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents
3977 Introduction to Extents
3978 =======================
3980 An extent is a region of text within a buffer or string that has
3981 certain properties associated with it. The properties of an extent
3982 primarily affect the way the text contained in the extent is displayed.
3983 Extents can freely overlap each other in a buffer or string. Extents
3984 are invisible to functions that merely examine the text of a buffer or
3987 _Please note:_ An alternative way to add properties to a buffer or
3988 string is to use text properties. *Note Text Properties::.
3990 An extent is logically a Lisp object consisting of a start position,
3991 an end position, a buffer or string to which these positions refer, and
3992 a property list. As text is inserted into a buffer, the start and end
3993 positions of the extent are automatically adjusted as necessary to keep
3994 the extent referring to the same text in the buffer. If text is
3995 inserted at the boundary of an extent, the extent's `start-open' and
3996 `end-open' properties control whether the text is included as part of
3997 the extent. If the text bounded by an extent is deleted, the extent
3998 becomes "detached"; its start and end positions are no longer
3999 meaningful, but it maintains all its other properties and can later be
4000 reinserted into a buffer. (None of these considerations apply to
4001 strings, because text cannot be inserted into or deleted from a string.)
4003 Each extent has a face or list of faces associated with it, which
4004 controls the way in which the text bounded by the extent is displayed.
4005 If an extent's face is `nil' or its properties are partially undefined,
4006 the corresponding properties from the default face for the frame is
4007 used. If two or more extents overlap, or if a list of more than one
4008 face is specified for a particular extent, the corresponding faces are
4009 merged to determine the text's displayed properties. Every extent has
4010 a "priority" that determines which face takes precedence if the faces
4011 conflict. (If two extents have the same priority, the one that comes
4012 later in the display order takes precedence. *Note display order:
4013 Extent Endpoints.) Higher-numbered priority values correspond to a
4014 higher priority, and priority values can be negative. Every extent is
4015 created with a priority of 0, but this can be changed with
4016 `set-extent-priority'. Within a single extent with a list of faces,
4017 faces earlier in the list have a higher priority than faces later in
4020 Extents can be set to respond specially to key and mouse events
4021 within the extent. An extent's `keymap' property controls the effect of
4022 key and mouse strokes within the extent's text, and the `mouse-face'
4023 property controls whether the extent is highlighted when the mouse moves
4024 over it. *Note Extents and Events::.
4026 An extent can optionally have a "begin-glyph" or "end-glyph"
4027 associated with it. A begin-glyph or end-glyph is a pixmap or string
4028 that will be displayed either at the start or end of an extent or in the
4029 margin of the line that the start or end of the extent lies in,
4030 depending on the extent's layout policy. Begin-glyphs and end-glyphs
4031 are used to implement annotations, and you should use the annotation API
4032 functions in preference to the lower-level extent functions. For more
4033 information, *Note Annotations::.
4035 If an extent has its `detachable' property set, it will become
4036 "detached" (i.e. no longer in the buffer) when all its text is deleted.
4037 Otherwise, it will simply shrink down to zero-length and sit in the
4038 same place in the buffer. By default, the `detachable' property is set
4039 on newly-created extents. *Note Detached Extents::.
4041 If an extent has its `duplicable' property set, it will be
4042 remembered when a string is created from text bounded by the extent.
4043 When the string is re-inserted into a buffer, the extent will also be
4044 re-inserted. This mechanism is used in the kill, yank, and undo
4045 commands. *Note Duplicable Extents::.
4048 File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents
4050 Creating and Modifying Extents
4051 ==============================
4053 - Function: make-extent from to &optional buffer-or-string
4054 This function makes an extent for the range [FROM, TO) in
4055 BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults
4056 to the current buffer. Insertions at point TO will be outside of
4057 the extent; insertions at FROM will be inside the extent, causing
4058 the extent to grow (*note Extent Endpoints::). This is the same
4059 way that markers behave. The extent is initially detached if both
4060 FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
4061 to `nil', meaning the extent is in no buffer or string (*note
4062 Detached Extents::).
4064 - Function: delete-extent extent
4065 This function removes EXTENT from its buffer and destroys it.
4066 This does not modify the buffer's text, only its display
4067 properties. The extent cannot be used thereafter. To remove an
4068 extent in such a way that it can be re-inserted later, use
4069 `detach-extent'. *Note Detached Extents::.
4071 - Function: extent-object extent
4072 This function returns the buffer or string that EXTENT is in. If
4073 the return value is `nil', this means that the extent is detached;
4074 however, a detached extent will not necessarily return a value of
4077 - Function: extent-live-p object
4078 This function returns `t' if OBJECT is an extent that has not been
4079 deleted, and `nil' otherwise.
4082 File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents
4087 Every extent has a start position and an end position, and logically
4088 affects the characters between those positions. Normally the start and
4089 end positions must both be valid positions in the extent's buffer or
4090 string. However, both endpoints can be `nil', meaning the extent is
4091 detached. *Note Detached Extents::.
4093 Whether the extent overlaps its endpoints is governed by its
4094 `start-open' and `end-open' properties. Insertion of a character at a
4095 closed endpoint will expand the extent to include that character;
4096 insertion at an open endpoint will not. Similarly, functions such as
4097 `extent-at' that scan over all extents overlapping a particular
4098 position will include extents with a closed endpoint at that position,
4099 but not extents with an open endpoint.
4101 Note that the `start-closed' and `end-closed' properties are
4102 equivalent to `start-open' and `end-open' with the opposite sense.
4104 Both endpoints can be equal, in which case the extent includes no
4105 characters but still exists in the buffer or string. Zero-length
4106 extents are used to represent annotations (*note Annotations::) and can
4107 be used as a more powerful form of a marker. Deletion of all the
4108 characters in an extent may or may not result in a zero-length extent;
4109 this depends on the `detachable' property (*note Detached Extents::).
4110 Insertion at the position of a zero-length extent expands the extent if
4111 both endpoints are closed; goes before the extent if it has the
4112 `start-open' property; and goes after the extent if it has the
4113 `end-open' property. Zero-length extents with both the `start-open'
4114 and `end-open' properties are treated as if their starting point were
4115 closed. Deletion of a character on a side of a zero-length extent
4116 whose corresponding endpoint is closed causes the extent to be detached
4117 if its `detachable' property is set; if the corresponding endpoint is
4118 open, the extent remains in the buffer, moving as necessary.
4120 Extents are ordered within a buffer or string by increasing start
4121 position, and then by decreasing end position (this is called the
4124 - Function: extent-start-position extent
4125 This function returns the start position of EXTENT.
4127 - Function: extent-end-position extent
4128 This function returns the end position of EXTENT.
4130 - Function: extent-length extent
4131 This function returns the length of EXTENT in characters. If the
4132 extent is detached, this returns `0'. If the extent is not
4133 detached, this is equivalent to
4134 (- (extent-end-position EXTENT) (extent-start-position EXTENT))
4136 - Function: set-extent-endpoints extent start end &optional
4138 This function sets the start and end position of EXTENT to START
4139 and END. If both are `nil', this is equivalent to `detach-extent'.
4141 BUFFER-OR-STRING specifies the new buffer or string that the
4142 extent should be in, and defaults to EXTENT's buffer or string.
4143 (If `nil', and EXTENT is in no buffer and no string, it defaults
4144 to the current buffer.)
4146 See documentation on `detach-extent' for a discussion of undo
4150 File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents
4155 The following functions provide a simple way of determining the extents
4156 in a buffer or string. A number of more sophisticated primitives for
4157 mapping over the extents in a range of a buffer or string are also
4158 provided (*note Mapping Over Extents::). When reading through this
4159 section, keep in mind the way that extents are ordered (*note Extent
4162 - Function: extent-list &optional buffer-or-string from to flags
4164 This function returns a list of the extents in BUFFER-OR-STRING.
4165 BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
4166 and TO can be used to limit the range over which extents are
4167 returned; if omitted, all extents in the buffer or string are
4170 More specifically, if a range is specified using FROM and TO, only
4171 extents that overlap the range (i.e. begin or end inside of the
4172 range) are included in the list. FROM and TO default to the
4173 beginning and end of BUFFER-OR-STRING, respectively.
4175 FLAGS controls how end cases are treated. For a discussion of
4176 this, and exactly what "overlap" means, see `map-extents'.
4178 The optional arguments PROPERTY and VALUE can be used to further
4179 restrict which extents are returned. They have the same meaning
4180 as for `map-extents'.
4182 If you want to map a function over the extents in a buffer or
4183 string, consider using `map-extents' or `mapcar-extents' instead.
4185 See also the function `extents-at'.
4187 Functions that create extents must be prepared for the possibility
4188 that there are other extents in the same area, created by other
4189 functions. To deal with this, functions typically mark their own
4190 extents by setting a particular property on them. The following
4191 function makes it easier to locate those extents.
4193 - Function: extent-at pos &optional object property before at-flag
4194 This function finds the "smallest" extent (i.e., the last one in
4195 the display order) at (i.e., overlapping) POS in OBJECT (a buffer
4196 or string) having PROPERTY set. OBJECT defaults to the current
4197 buffer. PROPERTY defaults to `nil', meaning that any extent will
4198 do. Returns `nil' if there is no matching extent at POS. If the
4199 fourth argument BEFORE is not `nil', it must be an extent; any
4200 returned extent will precede that extent. This feature allows
4201 `extent-at' to be used by a loop over extents.
4203 AT-FLAG controls how end cases are handled (i.e. what "at" really
4204 means), and should be one of:
4209 An extent is at POS if it covers the character after POS.
4210 This is consistent with the way that text properties work.
4213 An extent is at POS if it covers the character before POS.
4216 An extent is at POS if it overlaps or abuts POS. This
4217 includes all zero-length extents at POS.
4219 Note that in all cases, the start-openness and end-openness of the
4220 extents considered is ignored. If you want to pay attention to
4221 those properties, you should use `map-extents', which gives you
4224 The following low-level functions are provided for explicitly
4225 traversing the extents in a buffer according to the display order.
4226 These functions are mostly intended for debugging--in normal operation,
4227 you should probably use `mapcar-extents' or `map-extents', or loop
4228 using the BEFORE argument to `extent-at', rather than creating a loop
4229 using `next-extent'.
4231 - Function: next-extent extent
4232 Given an extent EXTENT, this function returns the next extent in
4233 the buffer or string's display order. If EXTENT is a buffer or
4234 string, this returns the first extent in the buffer or string.
4236 - Function: previous-extent extent
4237 Given an extent EXTENT, this function returns the previous extent
4238 in the buffer or string's display order. If EXTENT is a buffer or
4239 string, this returns the last extent in the buffer or string.
4242 File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents
4244 Mapping Over Extents
4245 ====================
4247 The most basic and general function for mapping over extents is called
4248 `map-extents'. You should read through the definition of this function
4249 to familiarize yourself with the concepts and optional arguments
4250 involved. However, in practice you may find it more convenient to use
4251 the function `mapcar-extents' or to create a loop using the `before'
4252 argument to `extent-at' (*note Finding Extents::).
4254 - Function: map-extents function &optional object from to maparg flags
4256 This function maps FUNCTION over the extents which overlap a
4257 region in OBJECT. OBJECT is normally a buffer or string but could
4258 be an extent (see below). The region is normally bounded by
4259 [FROM, TO) (i.e. the beginning of the region is closed and the end
4260 of the region is open), but this can be changed with the FLAGS
4261 argument (see below for a complete discussion).
4263 FUNCTION is called with the arguments (extent, MAPARG). The
4264 arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
4265 default to the current buffer, the beginning of OBJECT, the end of
4266 OBJECT, `nil', and `nil', respectively. `map-extents' returns the
4267 first non-`nil' result produced by FUNCTION, and no more calls to
4268 FUNCTION are made after it returns non-`nil'.
4270 If OBJECT is an extent, FROM and TO default to the extent's
4271 endpoints, and the mapping omits that extent and its predecessors.
4272 This feature supports restarting a loop based on `map-extents'.
4273 Note: OBJECT must be attached to a buffer or string, and the
4274 mapping is done over that buffer or string.
4276 An extent overlaps the region if there is any point in the extent
4277 that is also in the region. (For the purpose of overlap,
4278 zero-length extents and regions are treated as closed on both ends
4279 regardless of their endpoints' specified open/closedness.) Note
4280 that the endpoints of an extent or region are considered to be in
4281 that extent or region if and only if the corresponding end is
4282 closed. For example, the extent [5,7] overlaps the region [2,5]
4283 because 5 is in both the extent and the region. However, (5,7]
4284 does not overlap [2,5] because 5 is not in the extent, and neither
4285 [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
4288 The optional FLAGS can be a symbol or a list of one or more
4289 symbols, modifying the behavior of `map-extents'. Allowed symbols
4293 The region's end is closed.
4296 The region's start is open.
4298 `all-extents-closed'
4299 Treat all extents as closed on both ends for the purpose of
4300 determining whether they overlap the region, irrespective of
4301 their actual open- or closedness.
4304 Treat all extents as open on both ends.
4306 `all-extents-closed-open'
4307 Treat all extents as start-closed, end-open.
4309 `all-extents-open-closed'
4310 Treat all extents as start-open, end-closed.
4313 In addition to the above conditions for extent overlap, the
4314 extent's start position must lie within the specified region.
4315 Note that, for this condition, open start positions are
4316 treated as if 0.5 was added to the endpoint's value, and open
4317 end positions are treated as if 0.5 was subtracted from the
4321 The extent's end position must lie within the region.
4323 `start-and-end-in-region'
4324 Both the extent's start and end positions must lie within the
4327 `start-or-end-in-region'
4328 Either the extent's start or end position must lie within the
4332 The condition specified by a `*-in-region' flag must _not_
4333 hold for the extent to be considered.
4335 At most one of `all-extents-closed', `all-extents-open',
4336 `all-extents-closed-open', and `all-extents-open-closed' may be
4339 At most one of `start-in-region', `end-in-region',
4340 `start-and-end-in-region', and `start-or-end-in-region' may be
4343 If optional arg PROPERTY is non-`nil', only extents with that
4344 property set on them will be visited. If optional arg VALUE is
4345 non-`nil', only extents whose value for that property is `eq' to
4346 VALUE will be visited.
4348 If you want to map over extents and accumulate a list of results,
4349 the following function may be more convenient than `map-extents'.
4351 - Function: mapcar-extents function &optional predicate
4352 buffer-or-string from to flags property value
4353 This function applies FUNCTION to all extents which overlap a
4354 region in BUFFER-OR-STRING. The region is delimited by FROM and
4355 TO. FUNCTION is called with one argument, the extent. A list of
4356 the values returned by FUNCTION is returned. An optional
4357 PREDICATE may be used to further limit the extents over which
4358 FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and
4359 VALUE may also be used to control the extents passed to PREDICATE
4360 or FUNCTION, and have the same meaning as in `map-extents'.
4362 - Function: map-extent-children function &optional object from to
4363 maparg flags property value
4364 This function is similar to `map-extents', but differs in that:
4366 * It only visits extents which start in the given region.
4368 * After visiting an extent E, it skips all other extents which
4369 start inside E but end before E's end.
4371 Thus, this function may be used to walk a tree of extents in a
4373 (defun walk-extents (buffer &optional ignore)
4374 (map-extent-children 'walk-extents buffer))
4376 - Function: extent-in-region-p extent &optional from to flags
4377 This function returns `t' if `map-extents' would visit EXTENT if
4378 called with the given arguments.
4381 File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
4383 Properties of Extents
4384 =====================
4386 Each extent has a property list associating property names with values.
4387 Some property names have predefined meanings, and can usually only
4388 assume particular values. Assigning other values to such a property
4389 either cause the value to be converted into a legal value (e.g.,
4390 assigning anything but `nil' to a Boolean property will cause the value
4391 of `t' to be assigned to the property) or will cause an error.
4392 Property names without predefined meanings can be assigned any value.
4393 An undefined property is equivalent to a property with a value of
4394 `nil', or with a particular default value in the case of properties
4395 with predefined meanings. Note that, when an extent is created, the
4396 `end-open' and `detachable' properties are set on it.
4398 If an extent has a parent, all of its properties actually derive
4399 from that parent (or from the root ancestor if the parent in turn has a
4400 parent), and setting a property of the extent actually sets that
4401 property on the parent. *Note Extent Parents::.
4403 - Function: extent-property extent property &optional default
4404 This function returns EXTENT's value for PROPERTY, or DEFAULT if
4405 no such property exists.
4407 - Function: extent-properties extent
4408 This function returns a list of all of EXTENT's properties that do
4409 not have the value of `nil' (or the default value, for properties
4410 with predefined meanings).
4412 - Function: set-extent-property extent property value
4413 This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
4414 predefined meaning, only certain values are allowed, and some
4415 values may be converted to others before being stored.)
4417 - Function: set-extent-properties extent plist
4418 Change some properties of EXTENT. PLIST is a property list. This
4419 is useful to change many extent properties at once.
4421 The following table lists the properties with predefined meanings,
4422 along with their allowable values.
4425 (Boolean) Whether the extent is detached. Setting this is the
4426 same as calling `detach-extent'. *Note Detached Extents::.
4429 (Boolean) Whether the extent has been deleted. Setting this is
4430 the same as calling `delete-extent'.
4433 (integer) The extent's redisplay priority. Defaults to 0. *Note
4434 priority: Intro to Extents. This property can also be set with
4435 `set-extent-priority' and accessed with `extent-priority'.
4438 (Boolean) Whether the start position of the extent is open,
4439 meaning that characters inserted at that position go outside of
4440 the extent. *Note Extent Endpoints::.
4443 (Boolean) Same as `start-open' but with the opposite sense.
4444 Setting this property clears `start-open' and vice-versa.
4447 (Boolean) Whether the end position of the extent is open, meaning
4448 that characters inserted at that position go outside of the
4449 extent. This is `t' by default. *Note Extent Endpoints::.
4452 (Boolean) Same as `end-open' but with the opposite sense. Setting
4453 this property clears `end-open' and vice-versa.
4456 (Boolean) Whether text within this extent will be unmodifiable.
4459 (face, face name, list of faces or face names, or `nil') The face
4460 in which to display the extent's text. This property can also be
4461 set with `set-extent-face' and accessed with `extent-face'. Note
4462 that if a list of faces is specified, the faces are merged
4463 together, with faces earlier in the list having priority over
4464 faces later in the list.
4467 (face, face name, list of faces or face names, or `nil') The face
4468 used to display the extent when the mouse moves over it. This
4469 property can also be set with `set-extent-mouse-face' and accessed
4470 with `extent-mouse-face'. Note that if a list of faces is
4471 specified, the faces are merged together, with faces earlier in
4472 the list having priority over faces later in the list. *Note
4473 Extents and Events::.
4476 (pointer glyph) The glyph used as the pointer when the mouse
4477 moves over the extent. This takes precedence over the
4478 `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
4479 for any reason this glyph is an invalid pointer, the standard
4480 glyphs will be used as fallbacks. *Note Mouse Pointer::.
4483 (Boolean) Whether this extent becomes detached when all of the
4484 text it covers is deleted. This is `t' by default. *Note
4488 (Boolean) Whether this extent should be copied into strings, so
4489 that kill, yank, and undo commands will restore or copy it. *Note
4490 Duplicable Extents::.
4493 (Boolean) Meaningful only in conjunction with `duplicable'. When
4494 this is set, there may be only one instance of this extent
4495 attached at a time. *Note Duplicable Extents::.
4498 (Boolean) If `t', text under this extent will not be displayed -
4499 it will look as if the text and the begin-glyph is not there at
4500 all. The end-glyph will still be displayed.
4503 (keymap or `nil') This keymap is consulted for mouse clicks on this
4504 extent or keypresses made while `point' is within the extent.
4505 *Note Extents and Events::.
4508 This is a hook that is run when a duplicable extent is about to be
4509 copied from a buffer to a string (or the kill ring). *Note
4510 Duplicable Extents::.
4513 This is a hook that is run when a duplicable extent is about to be
4514 copied from a string (or the kill ring) into a buffer. *Note
4515 Duplicable Extents::.
4518 (glyph or `nil') This extent's begin glyph. *Note Annotations::.
4521 (glyph or `nil') This extent's end glyph. *Note Annotations::.
4523 `begin-glyph-layout'
4524 (`text', `whitespace', `inside-margin', or `outside-margin') The
4525 layout policy for this extent's begin glyph. Defaults to `text'.
4526 *Note Annotations::.
4529 (`text', `whitespace', `inside-margin', or `outside-margin') The
4530 layout policy for this extent's end glyph. Defaults to `text'.
4531 *Note Annotations::.
4533 `initial-redisplay-function'
4534 (any funcallable object) The function to be called the first time
4535 (a part of) the extent is redisplayed. It will be called with the
4536 extent as its argument.
4538 This is used by `lazy-shot' to implement lazy font-locking. The
4539 functionality is still experimental, and may change without further
4542 The following convenience functions are provided for accessing
4543 particular properties of an extent.
4545 - Function: extent-face extent
4546 This function returns the `face' property of EXTENT. This might
4547 also return a list of face names. Do not modify this list
4548 directly! Instead, use `set-extent-face'.
4550 Note that you can use `eq' to compare lists of faces as returned
4551 by `extent-face'. In other words, if you set the face of two
4552 different extents to two lists that are `equal' but not `eq', then
4553 the return value of `extent-face' on the two extents will return
4556 - Function: extent-mouse-face extent
4557 This function returns the `mouse-face' property of EXTENT. This
4558 might also return a list of face names. Do not modify this list
4559 directly! Instead, use `set-extent-mouse-face'.
4561 Note that you can use `eq' to compare lists of faces as returned
4562 by `extent-mouse-face', just like for `extent-face'.
4564 - Function: extent-priority extent
4565 This function returns the `priority' property of EXTENT.
4567 - Function: extent-keymap extent
4568 This function returns the `keymap' property of EXTENT.
4570 - Function: extent-begin-glyph-layout extent
4571 This function returns the `begin-glyph-layout' property of EXTENT,
4572 i.e. the layout policy associated with the EXTENT's begin glyph.
4574 - Function: extent-end-glyph-layout extent
4575 This function returns the `end-glyph-layout' property of EXTENT,
4576 i.e. the layout policy associated with the EXTENT's end glyph.
4578 - Function: extent-begin-glyph extent
4579 This function returns the `begin-glyph' property of EXTENT, i.e.
4580 the glyph object displayed at the beginning of EXTENT. If there
4581 is none, `nil' is returned.
4583 - Function: extent-end-glyph extent
4584 This function returns the `end-glyph' property of EXTENT, i.e. the
4585 glyph object displayed at the end of EXTENT. If there is none,
4588 The following convenience functions are provided for setting
4589 particular properties of an extent.
4591 - Function: set-extent-priority extent priority
4592 This function sets the `priority' property of EXTENT to PRIORITY.
4594 - Function: set-extent-face extent face
4595 This function sets the `face' property of EXTENT to FACE.
4597 - Function: set-extent-mouse-face extent face
4598 This function sets the `mouse-face' property of EXTENT to FACE.
4600 - Function: set-extent-keymap extent keymap
4601 This function sets the `keymap' property of EXTENT to KEYMAP.
4602 KEYMAP must be either a keymap object, or `nil'.
4604 - Function: set-extent-begin-glyph-layout extent layout
4605 This function sets the `begin-glyph-layout' property of EXTENT to
4608 - Function: set-extent-end-glyph-layout extent layout
4609 This function sets the `end-glyph-layout' property of EXTENT to
4612 - Function: set-extent-begin-glyph extent begin-glyph &optional layout
4613 This function sets the `begin-glyph' and `glyph-layout' properties
4614 of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
4615 defaults to `text' if not specified.)
4617 - Function: set-extent-end-glyph extent end-glyph &optional layout
4618 This function sets the `end-glyph' and `glyph-layout' properties
4619 of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
4620 to `text' if not specified.)
4622 - Function: set-extent-initial-redisplay-function extent function
4623 This function sets the `initial-redisplay-function' property of the
4627 File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
4632 A detached extent is an extent that is not attached to a buffer or
4633 string but can be re-inserted. Detached extents have a start position
4634 and end position of `nil'. Extents can be explicitly detached using
4635 `detach-extent'. An extent is also detached when all of its characters
4636 are all killed by a deletion, if its `detachable' property is set; if
4637 this property is not set, the extent becomes a zero-length extent.
4638 (Zero-length extents with the `detachable' property set behave
4639 specially. *Note zero-length extents: Extent Endpoints.)
4641 - Function: detach-extent extent
4642 This function detaches EXTENT from its buffer or string. If
4643 EXTENT has the `duplicable' property, its detachment is tracked by
4644 the undo mechanism. *Note Duplicable Extents::.
4646 - Function: extent-detached-p extent
4647 This function returns `nil' if EXTENT is detached, and `t'
4650 - Function: copy-extent extent &optional object
4651 This function makes a copy of EXTENT. It is initially detached.
4652 Optional argument OBJECT defaults to EXTENT's object (normally a
4653 buffer or string, but could be `nil').
4655 - Function: insert-extent extent &optional start end no-hooks object
4656 This function inserts EXTENT from START to END in OBJECT (a buffer
4657 or string). If EXTENT is detached from a different buffer or
4658 string, or in most cases when EXTENT is already attached, the
4659 extent will first be copied as if with `copy-extent'. This
4660 function operates the same as if `insert' were called on a string
4661 whose extent data calls for EXTENT to be inserted, except that if
4662 NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
4663 invoked. *Note Duplicable Extents::.
4666 File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
4671 An extent can have a parent extent set for it. If this is the case,
4672 the extent derives all its properties from that extent and has no
4673 properties of its own. The only "properties" that the extent keeps are
4674 the buffer or string it refers to and the start and end points. (More
4675 correctly, the extent's own properties are shadowed. If you later
4676 change the extent to have no parent, its own properties will become
4679 It is possible for an extent's parent to itself have a parent, and
4680 so on. Through this, a whole tree of extents can be created, all
4681 deriving their properties from one root extent. Note, however, that
4682 you cannot create an inheritance loop--this is explicitly disallowed.
4684 Parent extents are used to implement the extents over the modeline.
4686 - Function: set-extent-parent extent parent
4687 This function sets the parent of EXTENT to PARENT. If PARENT is
4688 `nil', the extent is set to have no parent.
4690 - Function: extent-parent extent
4691 This function return the parents (if any) of EXTENT, or `nil'.
4693 - Function: extent-children extent
4694 This function returns a list of the children (if any) of EXTENT.
4695 The children of an extent are all those extents whose parent is
4696 that extent. This function does not recursively trace children of
4699 - Function: extent-descendants extent
4700 This function returns a list of all descendants of EXTENT,
4701 including EXTENT. This recursively applies `extent-children' to
4702 any children of EXTENT, until no more children can be found.
4705 File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
4710 If an extent has the `duplicable' property, it will be copied into
4711 strings, so that kill, yank, and undo commands will restore or copy it.
4715 * When a string is created using `buffer-substring' or
4716 `buffer-string', any duplicable extents in the region corresponding
4717 to the string will be copied into the string (*note Buffer
4718 Contents::). When the string is inserted into a buffer using
4719 `insert', `insert-before-markers', `insert-buffer' or
4720 `insert-buffer-substring', the extents in the string will be copied
4721 back into the buffer (*note Insertion::). The extents in a string
4722 can, of course, be retrieved explicitly using the standard extent
4723 primitives over the string.
4725 * Similarly, when text is copied or cut into the kill ring, any
4726 duplicable extents will be remembered and reinserted later when
4727 the text is pasted back into a buffer.
4729 * When `concat' is called on strings, the extents in the strings are
4730 copied into the resulting string.
4732 * When `substring' is called on a string, the relevant extents are
4733 copied into the resulting string.
4735 * When a duplicable extent is detached by `detach-extent' or string
4736 deletion, or inserted by `insert-extent' or string insertion, the
4737 action is recorded by the undo mechanism so that it can be undone
4738 later. Note that if an extent gets detached and then a later undo
4739 causes the extent to get reinserted, the new extent will not be
4740 `eq' to the original extent.
4742 * Extent motion, face changes, and attachment via `make-extent' are
4743 not recorded by the undo mechanism. This means that extent changes
4744 which are to be undo-able must be performed by character editing,
4745 or by insertion and detachment of duplicable extents.
4747 * A duplicable extent's `copy-function' property, if non-`nil',
4748 should be a function, and will be run when a duplicable extent is
4749 about to be copied from a buffer to a string (or the kill ring).
4750 It is called with three arguments: the extent and the buffer
4751 positions within it which are being copied. If this function
4752 returns `nil', then the extent will not be copied; otherwise it
4755 * A duplicable extent's `paste-function' property, if non-`nil',
4756 should be a function, and will be run when a duplicable extent is
4757 about to be copied from a string (or the kill ring) into a buffer.
4758 It is called with three arguments: the original extent and the
4759 buffer positions which the copied extent will occupy. (This hook
4760 is run after the corresponding text has already been inserted into
4761 the buffer.) Note that the extent argument may be detached when
4762 this function is run. If this function returns `nil', no extent
4763 will be inserted. Otherwise, there will be an extent covering the
4766 Note: if the extent to be copied is already attached to the buffer
4767 and overlaps the new range, the extent will simply be extended and
4768 the `paste-function' will not be called.
4771 File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
4773 Interaction of Extents with Keyboard and Mouse Events
4774 =====================================================
4776 If an extent has the `mouse-face' property set, it will be highlighted
4777 when the mouse passes over it. This includes the begin-glyph, but not
4778 the end-glyph. Highlighting is accomplished by merging the extent's
4779 face with the face or faces specified by the `mouse-face' property.
4780 The effect is as if a pseudo-extent with the `mouse-face' face were
4781 inserted after the extent in the display order (*note Extent
4782 Endpoints::, display order).
4784 - Variable: mouse-highlight-priority
4785 This variable holds the priority to use when merging in the
4786 highlighting pseudo-extent. The default is 1000. This is
4787 purposely set very high so that the highlighting pseudo-extent
4788 shows up even if there are other extents with various priorities
4789 at the same location.
4791 You can also explicitly cause an extent to be highlighted. Only one
4792 extent at a time can be highlighted in this fashion, and any other
4793 highlighted extent will be de-highlighted.
4795 - Function: highlight-extent extent &optional highlight-p
4796 This function highlights (if HIGHLIGHT-P is non-`nil') or
4797 de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
4798 `mouse-face' property. (Nothing happens if EXTENT does not have
4799 the `mouse-face' property.)
4801 - Function: force-highlight-extent extent &optional highlight-p
4802 This function is similar to `highlight-extent' but highlights or
4803 de-highlights the extent regardless of whether it has the
4804 `mouse-face' property.
4806 If an extent has a `keymap' property, this keymap will be consulted
4807 for mouse clicks on the extent and keypresses made while `point' is
4808 within the extent. The behavior of mouse clicks and keystrokes not
4809 defined in the keymap is as normal for the buffer.
4812 File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
4817 If the Lisp file `atomic-extents' is loaded, then the atomic extent
4818 facility is available. An "atomic extent" is an extent for which
4819 `point' cannot be positioned anywhere within it. This ensures that
4820 when selecting text, either all or none of the extent is selected.
4822 To make an extent atomic, set its `atomic' property.
4825 File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
4830 A specifier is an object used to keep track of a property whose value
4831 should vary according to _display context_, a window, a frame, or
4832 device. The value of many built-in properties, such as the font,
4833 foreground, background, and such properties of a face and variables
4834 such as `modeline-shadow-thickness' and `top-toolbar-height', is
4835 actually a specifier object. The specifier object, in turn, is
4836 "instanced" in a particular situation to yield the real value of the
4837 property in the current context.
4839 - Function: specifierp object
4840 This function returns non-`nil' if OBJECT is a specifier.
4844 * Introduction to Specifiers:: Specifiers provide a clean way for
4845 display and other properties to vary
4846 (under user control) in a wide variety
4848 * Simple Specifier Usage:: Getting started with specifiers.
4849 * Specifiers In-Depth:: Gory details about specifier innards.
4850 * Specifier Instancing:: Instancing means obtaining the ``value'' of
4851 a specifier in a particular context.
4852 * Specifier Types:: Specifiers come in different flavors.
4853 * Adding Specifications:: Specifications control a specifier's ``value''
4854 by giving conditions under which a
4855 particular value is valid.
4856 * Retrieving Specifications:: Querying a specifier's specifications.
4857 * Specifier Tag Functions:: Working with specifier tags.
4858 * Specifier Instancing Functions::
4859 Functions to instance a specifier.
4860 * Specifier Examples:: Making all this stuff clearer.
4861 * Creating Specifiers:: Creating specifiers for your own use.
4862 * Specifier Validation Functions::
4863 Validating the components of a specifier.
4864 * Other Specification Functions::
4865 Other ways of working with specifications.
4868 File: lispref.info, Node: Introduction to Specifiers, Next: Simple Specifier Usage, Up: Specifiers
4870 Introduction to Specifiers
4871 ==========================
4873 Perhaps the most useful way to explain specifiers is via an analogy.
4874 Emacs Lisp programmers are used to _buffer-local variables_ *Note
4875 Buffer-Local Variables::. For example, the variable `modeline-format',
4876 which controls the format of the modeline, can have different values
4877 depending on the particular buffer being edited. The variable has a
4878 default value which most modes will use, but a specialized package such
4879 as Calendar might change the variable so as to tailor the modeline to
4880 its own purposes. Other variables are perhaps best thought of as "mode
4881 local," such as font-lock keywords, but they are implemented as buffer
4884 Other properties (such as those that can be changed by the
4885 `modify-frame-parameters' function, for example the color of the text
4886 cursor) can have frame-local values, although it might also make sense
4887 for them to have buffer-local values. In other cases, you might want
4888 the property to vary depending on the particular window within the
4889 frame that applies (e.g. the top or bottom window in a split frame), the
4890 device type that that frame appears on (X or tty), etc. Perhaps you can
4891 envision some more complicated scenario where you want a particular
4892 value in a specified buffer, another value in all other buffers
4893 displayed on a particular frame, another value in all other buffers
4894 displayed in all other frames on any mono (two-color, e.g. black and
4895 white only) displays, and a default value in all other circumstances.
4897 Specifiers generalize both buffer- and frame-local properties.
4898 Specifiers vary according to the _display_ context. Font-lock keywords
4899 in a buffer will be the same no matter which window the buffer is
4900 displayed in, but windows on TTY devices will simply not be capable of
4901 the flexibility that windows on modern GUI devices are. Specifiers
4902 provide a way for the programmer to _declare_ that an emphasized text
4903 should be italic on GUI devices and inverse video on TTYs. They also
4904 provide a way for the programmer to declare fallbacks, so that a color
4905 specified as "chartreuse" where possible can fall back to "yellow" on
4906 devices where only ANSI (4-bit) color is available. The complex
4907 calculations and device querying are transparent to both user and
4908 programmer. You ask for what you want; it's up to XEmacs to provide
4909 it, or a reasonable approximation.
4911 We call such a declaration a "specification". A "specification"
4912 applies in a particular "locale", which is a window, buffer, frame,
4913 device, or the global locale. The value part of the specification is
4914 called an "instantiator". The process of determining the value in a
4915 particular context, or "domain", is called "instantiation" or
4916 "instancing". A domain is a window, frame, or device.
4918 The difference between "locale" and "domain" is somewhat subtle.
4919 You may think of a locale as a class of domains, which may span
4920 different devices. Since the specification is abstract (a Lisp form),
4921 you can state it without reference to a device. On the other hand, when
4922 you instantiate a specification, you must know the type of the device.
4923 It is useless to specify that "blue means emphasis" on a monochrome
4924 device. Thus instantiation requires specification of the device on
4925 which it will be rendered.
4927 Thus a "specifier" allows a great deal of flexibility in controlling
4928 exactly what value a property has in which circumstances. Specifiers
4929 are most commonly used for display properties, such as an image or the
4930 foreground color of a face. As a simple example, you can specify that
4931 the foreground of the default face be
4933 * blue for a particular buffer
4935 * green for all other buffers
4937 As a more complicated example, you could specify that the foreground
4938 of the default face be
4940 * forest green for all buffers displayed in a particular Emacs
4941 window, or green if the X server doesn't recognize the color
4944 * blue for all buffers displayed in a particular frame
4946 * red for all other buffers displayed on a color device
4948 * white for all other buffers
4951 File: lispref.info, Node: Simple Specifier Usage, Next: Specifiers In-Depth, Prev: Introduction to Specifiers, Up: Specifiers
4953 Simple Specifier Usage
4954 ======================
4956 A useful specifier application is adding a button to a toolbar. XEmacs
4957 provides several toolbars, one along each edge of the frame. Normally
4958 only one is used at a time, the default. The default toolbar is
4959 actually a specifier object which is the value of `default-toolbar'.
4960 *Note Toolbar Intro::.
4962 The specification of a toolbar is simple: it is a list of buttons.
4963 Each button is a vector with four elements: an icon, a command, the
4964 enabled flag, and a help string. Let's retrieve the instance of the
4965 toolbar you see in the selected frame.
4967 (specifier-instance default-toolbar)
4969 The value returned is, as promised, a list of vectors. Now let's
4970 build up a button, and add it to the toolbar. Our button will invoke
4971 the last defined keyboard macro. This is an alternative to
4972 `name-last-kbd-macro' for creating a persistent macro, rather than an
4975 A toolbar button icon can be quite sophisticated, with different
4976 images for button up, button down, and disabled states, and a similar
4977 set with captions. We'll use a very simple icon, but we have to jump
4978 through a few non-obvious hoops designed to support the sophisticated
4979 applications. The rest of the button descriptor is straightforward.
4981 (setq toolbar-my-kbd-macro-button
4982 `[ (list (make-glyph "MyKbdMac"))
4983 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
4985 "Execute a previously defined keyboard macro." ])
4987 (set-specifier default-toolbar
4988 (cons toolbar-my-kbd-macro-button
4989 (specifier-specs default-toolbar 'global))
4992 To remove the button, just substitute the function `delete' for the
4995 What is the difference between `specifier-instance', which we used
4996 in the example of retrieving the toolbar descriptor, and
4997 `specifier-specs', which was used in the toolbar manipulating code?
4998 `specifier-specs' retrieves a copy of the instantiator, which is
4999 abstract and does not depend on context. `specifier-instance', on the
5000 other hand, actually instantiates the specification, and returns the
5001 result for the given context. Another way to express this is:
5002 `specifier-specs' takes a _locale_ as an argument, while
5003 `specifier-instance' takes a _domain_. The reason for providing
5004 `specifier-instance' is that sometimes you wish to see the object that
5005 XEmacs will actually use. `specifier-specs', on the other hand, shows
5006 you what the programmer (or user) requested. When a program
5007 manipulates specifications, clearly it's the latter that is desirable.
5009 In the case of the toolbar descriptor, it turns out that these are
5010 the same: the instancing process is trivial. However, many
5011 specifications have non-trivial instancing. Compare the results of the
5012 following forms on my system. (The `(cdr (first ...))' form is due to
5013 my use of Mule. On non-Mule XEmacsen, just use `specifier-specs'.)
5015 (cdr (first (specifier-specs (face-font 'default) 'global)))
5016 => "-*--14-*jisx0208*-0"
5018 (specifier-instance (face-font 'default))
5019 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
5021 In this case, `specifier-instance' returns an opaque object;
5022 programs can't work on it, they can only pass it around. Worse, in some
5023 environments the instantiation will fail, resulting in a different value
5024 (when another instantiation succeeds), or worse yet, an error, if all
5025 attempts to instance the specifier fail. `specifier-instance' is
5026 context-dependent, even for the exact same specification.
5027 `specifier-specs' is deterministic, and only depends on the
5030 Note that in the toolbar-changing code we operate in the global
5031 locale. This means that narrower locales, if they have specifications,
5032 will shadow our changes. (Specifier instancing does not merge
5033 specifications. It selects the "highest-priority successful
5034 specification" and instances that.)
5036 In fact, in our example, it seems pretty likely that different
5037 buffers _should_ have different buttons. (The icon can be the same, but
5038 the keyboard macro you create in a Dired buffer is highly unlikely to be
5039 useful in a LaTeX buffer!) Here's one way to implement this:
5041 (setq toolbar-my-kbd-macro-button
5042 `[ (list (make-glyph "MyKbdMac"))
5043 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
5045 "Execute a previously defined keyboard macro." ])
5047 (set-specifier default-toolbar
5048 (cons toolbar-my-kbd-macro-button
5049 (cond ((specifier-specs default-toolbar
5051 ((specifier-specs default-toolbar
5055 Finally, a cautionary note: the use of `specifier-specs' in the code
5056 above is for expository purposes. Don't use it in production code. In
5057 fact, the `set-specifier' form above is likely to fail occasionally,
5058 because you can add many specifications for the same locale.
5060 In these cases, `specifier-specs' will return a list. A further
5061 refinement is that a specification may be associated with a set of
5062 "specifier tags". If the list of specifier tags is non-nil, then
5063 `specifier-specs' will return a cons of the tag set and the
5064 instantiator. Evidently `specifier-specs' is a bit unreliable. (For
5065 toolbars, the code above should work 99% of the time, because toolbars
5066 are rarely changed. Since instantiation is trivial, multiple specs are
5067 not useful--the first one always succeeds.)
5069 In fact, `specifier-specs' is intended to be used to display specs
5070 to humans with a minimum of clutter. The robust way to access
5071 specifications is via `specifier-spec-list'. *Note Adding
5072 Specifications::, for the definition of "spec-list". *Note Retrieving
5073 Specifications::, for documentation of `specifier-specs' and
5074 `specifier-spec-list'. To get the desired effect, replace the form
5075 `(specifier-spec default-toolbar 'global)' with
5077 (cdr (second (first (specifier-spec-list default-toolbar 'global))))
5079 (It should be obvious why the example uses the lazy unreliable
5083 File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Simple Specifier Usage, Up: Specifiers
5085 In-Depth Overview of a Specifier
5086 ================================
5088 Having variables vary according the editing context is very useful, and
5089 the buffer is the natural "atomic" unit of editing context. In a GUI
5090 environment, it can be similarly useful to have variables whose values
5091 vary according to display context. The atomic unit of display context
5092 is the Emacs window. Buffers are cleanly grouped by modes, but windows
5093 are not so easily pigeonholed. On the one hand, a window displays a
5094 buffer, and thus one possible hierarchy is window, buffer, mode. On the
5095 other, a window is a component of a frame. This generates the window,
5096 frame, device hierarchy. Finally, there are objects such as toolbars
5097 whose properties are described by specifiers. These do not fit
5098 naturally into either hierarchy. This problem is as yet not cleanly
5101 Another potential source of conceptual confusion is the instantiation
5102 process. Instantiating a buffer-local variable is simple: at any given
5103 point in time there is a current buffer, and its local values are used
5104 and set whenever the variable is accessed, unless the programmer goes to
5105 some special effort (uses `default-value' and `set-default'. However,
5106 a specifier object encapsulates a set of "specifications", each of
5107 which says what its value should be if a particular condition applies.
5108 Several such conditions might apply simultaneously in a given window.
5110 For example, one specification might be "The value should be
5111 darkseagreen2 on X devices" another might be "The value should be blue
5112 in the *Help* buffer". So what do we do for "the *Help* buffer on an X
5113 device"? The answer is simple: give each type of locale a priority and
5114 check them in priority order, returning the first instantiator that
5115 successfully instantiates a value.
5117 Given a specifier, a logical question is "What is its value in a
5118 particular situation?" This involves looking through the specifications
5119 to see which ones apply to this particular situation, and perhaps
5120 preferring one over another if more than one applies. In specifier
5121 terminology, a "particular situation" is called a "domain", and
5122 determining its value in a particular domain is called "instancing".
5123 Most of the time, a domain is identified by a particular window. For
5124 example, if the redisplay engine is drawing text in the default face in
5125 a particular window, it retrieves the specifier for the foreground color
5126 of the default face and "instances" it in the domain given by that
5127 window; in other words, it asks the specifier, "What is your value in
5130 Note that the redisplay example is in a sense canonical. That is,
5131 specifiers are designed to present a uniform and _efficient_ API to
5132 redisplay. It is the efficiency constraint that motivates the
5133 introduction of specifier tags, and many restrictions on access (for
5134 example, a buffer is not a domain, and you cannot instantiate a
5135 specifier over a buffer).
5137 More specifically, a specifier contains a set of "specifications",
5138 each of which associates a "locale" (a window object, a buffer object,
5139 a frame object, a device object, or the symbol `global') with an
5140 "inst-list", which is a list of one or more "inst-pairs". (For each
5141 possible locale, there can be at most one specification containing that
5142 locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
5143 zero or more symbols, or "tags") and an "instantiator" (the allowed
5144 form of this varies depending on the type of specifier). In a given
5145 specification, there may be more than one inst-pair with the same tag
5146 set; this is unlike for locales.
5148 The tag set is used to restrict the sorts of devices over which the
5149 instantiator is valid and to uniquely identify instantiators added by a
5150 particular application, so that different applications can work on the
5151 same specifier and not interfere with each other. Each tag can have a
5152 "predicate" associated with it, which is a function of one argument (a
5153 device) that specifies whether the tag matches that particular device.
5154 (If a tag does not have a predicate, it matches all devices.) All tags
5155 in a tag set must match a device for the associated inst-pair to be
5156 instantiable over that device. (A null tag set is perfectly valid, and
5157 trivially matches all devices.)
5159 The valid device types (normally `x', `tty', and `stream') and
5160 device classes (normally `color', `grayscale', and `mono') can always
5161 be used as tags, and match devices of the associated type or class
5162 (*note Consoles and Devices::). User-defined tags may be defined, with
5163 an optional predicate specified. An application can create its own
5164 tag, use it to mark all its instantiators, and be fairly confident that
5165 it will not interfere with other applications that modify the same
5166 specifier--Functions that add a specification to a specifier usually
5167 only overwrite existing inst-pairs with the same tag set as was given,
5168 and a particular tag or tag set can be specified when removing
5171 When a specifier is instanced in a domain, both the locale and the
5172 tag set can be viewed as specifying necessary conditions that must
5173 apply in that domain for an instantiator to be considered as a possible
5174 result of the instancing. More specific locales always override more
5175 general locales (thus, there is no particular ordering of the
5176 specifications in a specifier); however, the tag sets are simply
5177 considered in the order that the inst-pairs occur in the
5178 specification's inst-list.
5180 Note also that the actual object that results from the instancing
5181 (called an "instance object") may not be the same as the instantiator
5182 from which it was derived. For some specifier types (such as integer
5183 specifiers and boolean specifiers), the instantiator will be returned
5184 directly as the instance object. For other types, however, this is not
5185 the case. For example, for font specifiers, the instantiator is a
5186 font-description string and the instance object is a font-instance
5187 object, which describes how the font is displayed on a particular
5188 device. A font-instance object encapsulates such things as the actual
5189 font name used to display the font on that device (a font-description
5190 string under X is usually a wildcard specification that may resolve to
5191 different font names, with possibly different foundries, widths, etc.,
5192 on different devices), the extra properties of that font on that
5193 device, etc. Furthermore, this conversion (called "instantiation")
5194 might fail--a font or color might not exist on a particular device, for
5198 File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
5200 How a Specifier Is Instanced
5201 ============================
5203 Instancing of a specifier in a particular window domain proceeds as
5206 * First, XEmacs searches for a specification whose locale is the
5207 same as the window. If that fails, the search is repeated,
5208 looking for a locale that is the same as the window's buffer. If
5209 that fails, the search is repeated using the window's frame, then
5210 using the device that frame is on. Finally, the specification
5211 whose locale is the symbol `global' (if there is such a
5212 specification) is considered.
5214 * The inst-pairs contained in the specification that was found are
5215 considered in their order in the inst-list, looking for one whose
5216 tag set matches the device that is derived from the window domain.
5217 (The tag set is an unordered list of zero or more tag symbols.
5218 For all tags that have predicates associated with them, the
5219 predicate must match the device.)
5221 * If a matching tag set is found, the corresponding instantiator is
5222 passed to the specifier's instantiation method, which is specific
5223 to the type of the specifier. If it succeeds, the resulting
5224 instance object is returned as the result of the instancing and
5225 the instancing is done. Otherwise, the operation continues,
5226 looking for another matching inst-pair in the current
5229 * When there are no more inst-pairs to be considered in the current
5230 specification, the search starts over, looking for another
5231 specification as in the first step above.
5233 * If all specifications are exhausted and no instance object can be
5234 derived, the instancing fails. (Actually, this is not completely
5235 true. Some specifier objects for built-in properties have a
5236 "fallback" value, which is either an inst-list or another
5237 specifier object, that is consulted if the instancing is about to
5238 fail. If it is an inst-list, the searching proceeds using the
5239 inst-pairs in that list. If it is a specifier, the entire
5240 instancing starts over using that specifier instead of the given
5241 one. Fallback values are set by the C code and cannot be
5242 modified, except perhaps indirectly, using any Lisp functions.
5243 The purpose of them is to supply some values to make sure that
5244 instancing of built-in properties can't fail and to implement some
5245 basic specifier inheritance, such as the fact that faces inherit
5246 their properties from the `default' face.)
5248 It is also possible to instance a specifier over a frame domain or
5249 device domain instead of over a window domain. The C code, for example,
5250 instances the `top-toolbar-height' variable over a frame domain in
5251 order to determine the height of a frame's top toolbar. Instancing over
5252 a frame or device is similar to instancing over a window except that
5253 specifications for locales that cannot be derived from the domain are
5254 ignored. Specifically, instancing over a frame looks first for frame
5255 locales, then device locales, then the `global' locale. Instancing
5256 over a device domain looks only for device locales and the `global'
5260 File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
5265 There are various different types of specifiers. The type of a
5266 specifier controls what sorts of instantiators are valid, how an
5267 instantiator is instantiated, etc. Here is a list of built-in specifier
5271 The valid instantiators are the symbols `t' and `nil'. Instance
5272 objects are the same as instantiators so no special instantiation
5276 The valid instantiators are integers. Instance objects are the
5277 same as instantiators so no special instantiation function is
5278 needed. `modeline-shadow-thickness' is an example of an integer
5279 specifier (negative thicknesses indicate that the shadow is drawn
5280 recessed instead of raised).
5283 The valid instantiators are natnums (non-negative integers).
5284 Instance objects are the same as instantiators so no special
5285 instantiation function is needed. Natnum specifiers are used for
5286 dimension variables such as `top-toolbar-height'.
5289 All Lisp objects are valid instantiators. Instance objects are
5290 the same as instantiators so no special instantiation function is
5294 The valid instantiators are strings describing fonts or vectors
5295 indicating inheritance from the font of some face. Instance
5296 objects are font-instance objects, which are specific to a
5297 particular device. The instantiation method for font specifiers
5298 can fail, unlike for integer, natnum, boolean, and generic
5302 The valid instantiators are strings describing colors or vectors
5303 indicating inheritance from the foreground or background of some
5304 face. Instance objects are color-instance objects, which are
5305 specific to a particular device. The instantiation method for
5306 color specifiers can fail, as for font specifiers.
5309 Images are perhaps the most complicated type of built-in
5310 specifier. The valid instantiators are strings (a filename,
5311 inline data for a pixmap, or text to be displayed in a text glyph)
5312 or vectors describing inline data of various sorts or indicating
5313 inheritance from the background-pixmap property of some face.
5314 Instance objects are either strings (for text images),
5315 image-instance objects (for pixmap images), or subwindow objects
5316 (for subwindow images). The instantiation method for image
5317 specifiers can fail, as for font and color specifiers.
5320 The valid instantiators are the symbols `t' and `nil' and vectors
5321 indicating inheritance from a boolean property of some face.
5322 Specifiers of this sort are used for all of the built-in boolean
5323 properties of faces. Instance objects are either the symbol `t'
5324 or the symbol `nil'.
5327 The valid instantiators are toolbar descriptors, which are lists
5328 of toolbar-button descriptors (each of which is a vector of two or
5329 four elements). *Note Toolbar::, for more information.
5331 Color and font instance objects can also be used in turn as
5332 instantiators for a new color or font instance object. Since these
5333 instance objects are device-specific, the instantiator can be used
5334 directly as the new instance object, but only if they are of the same
5335 device. If the devices differ, the base color or font of the
5336 instantiating object is effectively used instead as the instantiator.
5338 *Note Faces and Window-System Objects::, for more information on
5339 fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more
5340 information about image specifiers. *Note Toolbar::, for more
5341 information on toolbar specifiers.
5343 - Function: specifier-type specifier
5344 This function returns the type of SPECIFIER. The returned value
5345 will be a symbol: one of `integer', `boolean', etc., as listed in
5348 Functions are also provided to query whether an object is a
5349 particular kind of specifier:
5351 - Function: boolean-specifier-p object
5352 This function returns non-`nil' if OBJECT is a boolean specifier.
5354 - Function: integer-specifier-p object
5355 This function returns non-`nil' if OBJECT is an integer specifier.
5357 - Function: natnum-specifier-p object
5358 This function returns non-`nil' if OBJECT is a natnum specifier.
5360 - Function: generic-specifier-p object
5361 This function returns non-`nil' if OBJECT is a generic specifier.
5363 - Function: face-boolean-specifier-p object
5364 This function returns non-`nil' if OBJECT is a face-boolean
5367 - Function: toolbar-specifier-p object
5368 This function returns non-`nil' if OBJECT is a toolbar specifier.
5370 - Function: font-specifier-p object
5371 This function returns non-`nil' if OBJECT is a font specifier.
5373 - Function: color-specifier-p object
5374 This function returns non-`nil' if OBJECT is a color specifier.
5376 - Function: image-specifier-p object
5377 This function returns non-`nil' if OBJECT is an image specifier.
5380 File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
5382 Adding specifications to a Specifier
5383 ====================================
5385 - Function: add-spec-to-specifier specifier instantiator &optional
5386 locale tag-set how-to-add
5387 This function adds a specification to SPECIFIER. The
5388 specification maps from LOCALE (which should be a window, buffer,
5389 frame, device, or the symbol `global', and defaults to `global')
5390 to INSTANTIATOR, whose allowed values depend on the type of the
5391 specifier. Optional argument TAG-SET limits the instantiator to
5392 apply only to the specified tag set, which should be a list of
5393 tags all of which must match the device being instantiated over
5394 (tags are a device type, a device class, or tags defined with
5395 `define-specifier-tag'). Specifying a single symbol for TAG-SET
5396 is equivalent to specifying a one-element list containing that
5397 symbol. Optional argument HOW-TO-ADD specifies what to do if
5398 there are already specifications in the specifier. It should be
5402 Put at the beginning of the current list of instantiators for
5406 Add to the end of the current list of instantiators for
5409 `remove-tag-set-prepend'
5410 This is the default. Remove any existing instantiators whose
5411 tag set is the same as TAG-SET; then put the new instantiator
5412 at the beginning of the current list.
5414 `remove-tag-set-append'
5415 Remove any existing instantiators whose tag set is the same as
5416 TAG-SET; then put the new instantiator at the end of the
5420 Remove all previous instantiators for this locale before
5421 adding the new spec.
5423 `remove-locale-type'
5424 Remove all specifications for all locales of the same type as
5425 LOCALE (this includes LOCALE itself) before adding the new
5429 Remove all specifications from the specifier before adding
5432 `remove-tag-set-prepend' is the default.
5434 You can retrieve the specifications for a particular locale or
5435 locale type with the function `specifier-spec-list' or
5438 - Function: add-spec-list-to-specifier specifier spec-list &optional
5440 This function adds a "spec-list" (a list of specifications) to
5441 SPECIFIER. The format of a spec-list is
5443 `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
5447 * LOCALE := a window, a buffer, a frame, a device, or `global'
5449 * TAG-SET := an unordered list of zero or more TAGS, each of
5452 * TAG := a device class (*note Consoles and Devices::), a
5453 device type, or a tag defined with `define-specifier-tag'
5455 * INSTANTIATOR := format determined by the type of specifier
5457 The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A
5458 list of inst-pairs is called an "inst-list". The pair `(LOCALE .
5459 INST-LIST)' is called a "specification". A spec-list, then, can
5460 be viewed as a list of specifications.
5462 HOW-TO-ADD specifies how to combine the new specifications with
5463 the existing ones, and has the same semantics as for
5464 `add-spec-to-specifier'.
5466 The higher-level function `set-specifier' is often more convenient
5467 because it allows abbreviations of spec-lists to be used instead
5468 of the heavily nested canonical syntax. However, one should take
5469 great care in using them with specifiers types which can have lists
5470 as instantiators, such as toolbar specifiers and generic
5471 specifiers. In those cases it's probably best to use
5472 `add-spec-to-specifier' or `add-spec-list-to-specifier'.
5474 - Special Form: let-specifier specifier-list &rest body
5475 This special form temporarily adds specifications to specifiers,
5476 evaluates forms in BODY and restores the specifiers to their
5477 previous states. The specifiers and their temporary
5478 specifications are listed in SPECIFIER-LIST.
5480 The format of SPECIFIER-LIST is
5482 ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
5484 SPECIFIER is the specifier to be temporarily modified. VALUE is
5485 the instantiator to be temporarily added to specifier in LOCALE.
5486 LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
5487 `add-spec-to-specifier'.
5489 This special form is implemented as a macro; the code resulting
5490 from macro expansion will add specifications to specifiers using
5491 `add-spec-to-specifier'. After forms in BODY are evaluated, the
5492 temporary specifications are removed and old specifier spec-lists
5495 LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
5496 `nil'. The value of the last form in BODY is returned.
5498 NOTE: If you want the specifier's instance to change in all
5499 circumstances, use `(selected-window)' as the LOCALE. If LOCALE
5500 is `nil' or omitted, it defaults to `global'.
5502 The following example removes the 3D modeline effect in the
5503 currently selected window for the duration of a second:
5505 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
5508 - Function: set-specifier specifier value &optional locale tag-set
5510 This function adds some specifications to SPECIFIER. VALUE can be
5511 a single instantiator or tagged instantiator (added as a global
5512 specification), a list of tagged and/or untagged instantiators
5513 (added as a global specification), a cons of a locale and
5514 instantiator or locale and instantiator list, a list of such
5515 conses, or nearly any other reasonable form. More specifically,
5516 VALUE can be anything accepted by `canonicalize-spec-list'
5519 LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
5520 `add-spec-to-specifier'.
5522 Note that `set-specifier' is exactly complementary to
5523 `specifier-specs' except in the case where SPECIFIER has no specs
5524 at all in it but `nil' is a valid instantiator (in that case,
5525 `specifier-specs' will return `nil' (meaning no specs) and
5526 `set-specifier' will interpret the `nil' as meaning "I'm adding a
5527 global instantiator and its value is `nil'"), or in strange cases
5528 where there is an ambiguity between a spec-list and an inst-list,
5529 etc. (The built-in specifier types are designed in such a way as
5530 to avoid any such ambiguities.) For robust code, `set-specifier'
5531 should probably be avoided for specifier types which accept lists
5532 as instantiators (currently toolbar specifiers and generic
5535 If you want to work with spec-lists, you should probably not use
5536 these functions, but should use the lower-level functions
5537 `specifier-spec-list' and `add-spec-list-to-specifier'. These
5538 functions always work with fully-qualified spec-lists; thus, there
5541 - Function: canonicalize-inst-pair inst-pair specifier-type &optional
5543 This function canonicalizes the given INST-PAIR.
5545 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5548 Canonicalizing means converting to the full form for an inst-pair,
5549 i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator
5550 is given a tag set of `nil' (the empty set), and a single tag is
5551 converted into a tag set consisting only of that tag.
5553 If NOERROR is non-`nil', signal an error if the inst-pair is
5554 invalid; otherwise return `t'.
5556 - Function: canonicalize-inst-list inst-list specifier-type &optional
5558 This function canonicalizes the given INST-LIST (a list of
5561 SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
5564 Canonicalizing means converting to the full form for an inst-list,
5565 i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a
5566 single inst-pair or any abbreviation thereof or a list of
5567 (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
5569 If NOERROR is non-`nil', signal an error if the inst-list is
5570 invalid; otherwise return `t'.
5572 - Function: canonicalize-spec spec specifier-type &optional noerror
5573 This function canonicalizes the given SPEC (a specification).
5575 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5578 Canonicalizing means converting to the full form for a spec, i.e.
5579 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a
5580 possibly abbreviated inst-list or a cons of a locale and a
5581 possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
5583 If NOERROR is `nil', signal an error if the specification is
5584 invalid; otherwise return `t'.
5586 - Function: canonicalize-spec-list spec-list specifier-type &optional
5588 This function canonicalizes the given SPEC-LIST (a list of
5591 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5594 If NOERROR is `nil', signal an error if the spec-list is invalid;
5595 otherwise return `t' for an invalid spec-list. (Note that this
5596 cannot be confused with a canonical spec-list.)
5598 Canonicalizing means converting to the full form for a spec-list,
5599 i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This
5600 function accepts a possibly abbreviated specification or a list of
5601 such things. (See `canonicalize-spec'.) This is the function used
5602 to convert spec-lists accepted by `set-specifier' and such into a
5603 form suitable for `add-spec-list-to-specifier'.
5605 This function tries extremely hard to resolve any ambiguities, and
5606 the built-in specifier types (font, image, toolbar, etc.) are
5607 designed so that there won't be any ambiguities.
5609 The canonicalization algorithm is as follows:
5611 1. Attempt to parse SPEC-LIST as a single, possibly abbreviated,
5614 2. If that fails, attempt to parse SPEC-LIST as a list of
5615 (abbreviated) specifications.
5617 3. If that fails, SPEC-LIST is invalid.
5619 A possibly abbreviated specification SPEC is parsed by
5621 1. Attempt to parse SPEC as a possibly abbreviated inst-list.
5623 2. If that fails, attempt to parse SPEC as a cons of a locale
5624 and an (abbreviated) inst-list.
5626 3. If that fails, SPEC is invalid.
5628 A possibly abbreviated inst-list INST-LIST is parsed by
5630 1. Attempt to parse INST-LIST as a possibly abbreviated
5633 2. If that fails, attempt to parse INST-LIST as a list of
5634 (abbreviated) inst-pairs.
5636 3. If that fails, INST-LIST is invalid.
5638 A possibly abbreviated inst-pair INST-PAIR is parsed by
5640 1. Check if INST-PAIR is `valid-instantiator-p'.
5642 2. If not, check if INST-PAIR is a cons of something that is a
5643 tag, ie, `valid-specifier-tag-p', and something that is
5644 `valid-instantiator-p'.
5646 3. If not, check if INST-PAIR is a cons of a list of tags and
5647 something that is `valid-instantiator-p'.
5649 4. Otherwise, INST-PAIR is invalid.
5651 In summary, this function generally prefers more abbreviated forms.
5654 File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
5656 Retrieving the Specifications from a Specifier
5657 ==============================================
5659 - Function: specifier-spec-list specifier &optional locale tag-set
5661 This function returns the spec-list of specifications for
5662 SPECIFIER in LOCALE.
5664 If LOCALE is a particular locale (a window, buffer, frame, device,
5665 or the symbol `global'), a spec-list consisting of the
5666 specification for that locale will be returned.
5668 If LOCALE is a locale type (i.e. one of the symbols `window',
5669 `buffer', `frame', or `device'), a spec-list of the specifications
5670 for all locales of that type will be returned.
5672 If LOCALE is `nil' or the symbol `all', a spec-list of all
5673 specifications in SPECIFIER will be returned.
5675 LOCALE can also be a list of locales, locale types, and/or `all';
5676 the result is as if `specifier-spec-list' were called on each
5677 element of the list and the results concatenated together.
5679 Only instantiators where TAG-SET (a list of zero or more tags) is
5680 a subset of (or possibly equal to) the instantiator's tag set are
5681 returned. (The default value of `nil' is a subset of all tag sets,
5682 so in this case no instantiators will be screened out.) If EXACT-P
5683 is non-`nil', however, TAG-SET must be equal to an instantiator's
5684 tag set for the instantiator to be returned.
5686 - Function: specifier-specs specifier &optional locale tag-set exact-p
5687 This function returns the specification(s) for SPECIFIER in LOCALE.
5689 If LOCALE is a single locale or is a list of one element
5690 containing a single locale, then a "short form" of the
5691 instantiators for that locale will be returned. Otherwise, this
5692 function is identical to `specifier-spec-list'.
5694 The "short form" is designed for readability and not for ease of
5695 use in Lisp programs, and is as follows:
5697 1. If there is only one instantiator, then an inst-pair (i.e.
5698 cons of tag and instantiator) will be returned; otherwise a
5699 list of inst-pairs will be returned.
5701 2. For each inst-pair returned, if the instantiator's tag is
5702 `any', the tag will be removed and the instantiator itself
5703 will be returned instead of the inst-pair.
5705 3. If there is only one instantiator, its value is `nil', and
5706 its tag is `any', a one-element list containing `nil' will be
5707 returned rather than just `nil', to distinguish this case
5708 from there being no instantiators at all.
5711 - Function: specifier-fallback specifier
5712 This function returns the fallback value for SPECIFIER. Fallback
5713 values are provided by the C code for certain built-in specifiers
5714 to make sure that instancing won't fail even if all specs are
5715 removed from the specifier, or to implement simple inheritance
5716 behavior (e.g. this method is used to ensure that faces other than
5717 `default' inherit their attributes from `default'). By design,
5718 you cannot change the fallback value, and specifiers created with
5719 `make-specifier' will never have a fallback (although a similar,
5720 Lisp-accessible capability may be provided in the future to allow
5723 The fallback value will be an inst-list that is instanced like any
5724 other inst-list, a specifier of the same type as SPECIFIER
5725 (results in inheritance), or `nil' for no fallback.
5727 When you instance a specifier, you can explicitly request that the
5728 fallback not be consulted. (The C code does this, for example, when
5729 merging faces.) See `specifier-instance'.
5732 File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
5734 Working With Specifier Tags
5735 ===========================
5737 A specifier tag set is an entity that is attached to an instantiator
5738 and can be used to restrict the scope of that instantiator to a
5739 particular device class or device type and/or to mark instantiators
5740 added by a particular package so that they can be later removed.
5742 A specifier tag set consists of a list of zero or more specifier
5743 tags, each of which is a symbol that is recognized by XEmacs as a tag.
5744 (The valid device types and device classes are always tags, as are any
5745 tags defined by `define-specifier-tag'.) It is called a "tag set" (as
5746 opposed to a list) because the order of the tags or the number of times
5747 a particular tag occurs does not matter.
5749 Each tag has a predicate associated with it, which specifies whether
5750 that tag applies to a particular device. The tags which are device
5751 types and classes match devices of that type or class. User-defined
5752 tags can have any predicate, or none (meaning that all devices match).
5753 When attempting to instance a specifier, a particular instantiator is
5754 only considered if the device of the domain being instanced over matches
5755 all tags in the tag set attached to that instantiator.
5757 Most of the time, a tag set is not specified, and the instantiator
5758 gets a null tag set, which matches all devices.
5760 - Function: valid-specifier-tag-p tag
5761 This function returns non-`nil' if TAG is a valid specifier tag.
5763 - Function: valid-specifier-tag-set-p tag-set
5764 This function returns non-`nil' if TAG-SET is a valid specifier
5767 - Function: canonicalize-tag-set tag-set
5768 This function canonicalizes the given tag set. Two canonicalized
5769 tag sets can be compared with `equal' to see if they represent the
5770 same tag set. (Specifically, canonicalizing involves sorting by
5771 symbol name and removing duplicates.)
5773 - Function: device-matches-specifier-tag-set-p device tag-set
5774 This function returns non-`nil' if DEVICE matches specifier tag
5775 set TAG-SET. This means that DEVICE matches each tag in the tag
5778 - Function: define-specifier-tag tag &optional predicate
5779 This function defines a new specifier tag. If PREDICATE is
5780 specified, it should be a function of one argument (a device) that
5781 specifies whether the tag matches that particular device. If
5782 PREDICATE is omitted, the tag matches all devices.
5784 You can redefine an existing user-defined specifier tag. However,
5785 you cannot redefine the built-in specifier tags (the device types
5786 and classes) or the symbols `nil', `t', `all', or `global'.
5788 - Function: device-matching-specifier-tag-list &optional device
5789 This function returns a list of all specifier tags matching
5790 DEVICE. DEVICE defaults to the selected device if omitted.
5792 - Function: specifier-tag-list
5793 This function returns a list of all currently-defined specifier
5794 tags. This includes the built-in ones (the device types and
5797 - Function: specifier-tag-predicate tag
5798 This function returns the predicate for the given specifier tag.
5801 File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Examples, Prev: Specifier Tag Functions, Up: Specifiers
5803 Functions for Instancing a Specifier
5804 ====================================
5806 - Function: specifier-instance specifier &optional domain default
5808 This function instantiates SPECIFIER (returns its value) in
5809 DOMAIN. If no instance can be generated for this domain, return
5812 DOMAIN should be a window, frame, or device. Other values that
5813 are legal as a locale (e.g. a buffer) are not valid as a domain
5814 because they do not provide enough information to identify a
5815 particular device (see `valid-specifier-domain-p'). DOMAIN
5816 defaults to the selected window if omitted.
5818 "Instantiating" a specifier in a particular domain means
5819 determining the specifier's "value" in that domain. This is
5820 accomplished by searching through the specifications in the
5821 specifier that correspond to all locales that can be derived from
5822 the given domain, from specific to general. In most cases, the
5823 domain is an Emacs window. In that case specifications are
5824 searched for as follows:
5826 1. A specification whose locale is the window itself;
5828 2. A specification whose locale is the window's buffer;
5830 3. A specification whose locale is the window's frame;
5832 4. A specification whose locale is the window's frame's device;
5834 5. A specification whose locale is the symbol `global'.
5836 If all of those fail, then the C-code-provided fallback value for
5837 this specifier is consulted (see `specifier-fallback'). If it is
5838 an inst-list, then this function attempts to instantiate that list
5839 just as when a specification is located in the first five steps
5840 above. If the fallback is a specifier, `specifier-instance' is
5841 called recursively on this specifier and the return value used.
5842 Note, however, that if the optional argument NO-FALLBACK is
5843 non-`nil', the fallback value will not be consulted.
5845 Note that there may be more than one specification matching a
5846 particular locale; all such specifications are considered before
5847 looking for any specifications for more general locales. Any
5848 particular specification that is found may be rejected because it
5849 is tagged to a particular device class (e.g. `color') or device
5850 type (e.g. `x') or both and the device for the given domain does
5851 not match this, or because the specification is not valid for the
5852 device of the given domain (e.g. the font or color name does not
5853 exist for this particular X server).
5855 The returned value is dependent on the type of specifier. For
5856 example, for a font specifier (as returned by the `face-font'
5857 function), the returned value will be a font-instance object. For
5858 images, the returned value will be a string, pixmap, or subwindow.
5860 - Function: specifier-matching-instance specifier matchspec &optional
5861 domain default no-fallback
5862 This function returns an instance for SPECIFIER in DOMAIN that
5863 matches MATCHSPEC. If no instance can be generated for DOMAIN,
5866 This function is identical to `specifier-instance' except that a
5867 specification will only be considered if it matches MATCHSPEC.
5868 The definition of "match," and allowed values for MATCHSPEC, are
5869 dependent on the particular type of specifier. Here are some
5872 * For chartable (e.g. display table) specifiers, MATCHSPEC
5873 should be a character, and the specification (a chartable)
5874 must give a value for that character in order to be
5875 considered. This allows you to specify, _e.g._, a
5876 buffer-local display table that only gives values for
5877 particular characters. All other characters are handled as
5878 if the buffer-local display table is not there. (Chartable
5879 specifiers are not yet implemented.)
5881 * For font specifiers, MATCHSPEC should be a charset, and the
5882 specification (a font string) must have a registry that
5883 matches the charset's registry. (This only makes sense with
5884 Mule support.) This makes it easy to choose a font that can
5885 display a particular character. (This is what redisplay
5888 - Function: specifier-instance-from-inst-list specifier domain
5889 inst-list &optional default
5890 This function attempts to convert a particular inst-list into an
5891 instance. This attempts to instantiate INST-LIST in the given
5892 DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
5893 If the instantiation fails, DEFAULT is returned. In most
5894 circumstances, you should not use this function; use
5895 `specifier-instance' instead.
5898 File: lispref.info, Node: Specifier Examples, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
5900 Examples of Specifier Usage
5901 ===========================
5903 Now let us present an example to clarify the theoretical discussions we
5904 have been through. In this example, we will use the general specifier
5905 functions for clarity. Keep in mind that many types of specifiers, and
5906 some other types of objects that are associated with specifiers (e.g.
5907 faces), provide convenience functions making it easier to work with
5908 objects of that type.
5910 Let us consider the background color of the default face. A
5911 specifier is used to specify how that color will appear in different
5912 domains. First, let's retrieve the specifier:
5914 (setq sp (face-property 'default 'background))
5915 => #<color-specifier 0x3da>
5917 (specifier-specs sp)
5918 => ((#<buffer "device.c"> (nil . "forest green"))
5919 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
5920 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
5922 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
5923 (global ((tty) . "cyan") (nil . "white"))
5926 Then, say we want to determine what the background color of the
5927 default face is for the window currently displaying the buffer
5928 `*scratch*'. We call
5930 (get-buffer-window "*scratch*")
5931 => #<window on "*scratch*" 0x4ad>
5932 (window-frame (get-buffer-window "*scratch*"))
5933 => #<x-frame "emacs" 0x4ac>
5934 (specifier-instance sp (get-buffer-window "*scratch*"))
5935 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
5937 Note that we passed a window to `specifier-instance', not a buffer.
5938 We cannot pass a buffer because a buffer by itself does not provide
5939 enough information. The buffer might not be displayed anywhere at all,
5940 or could be displayed in many different frames on different devices.
5942 The result is arrived at like this:
5944 1. First, we look for a specification matching the buffer displayed
5945 in the window, i.e. `*scratch*'. There are none, so we proceed.
5947 2. Then, we look for a specification matching the window itself.
5948 Again, there are none.
5950 3. Then, we look for a specification matching the window's frame. The
5951 specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
5952 found. We call the instantiation method for colors, passing it the
5953 locale we were searching over (i.e. the window, in this case) and
5954 the instantiator (`"puke orange"'). However, the particular device
5955 which this window is on (let's say it's an X connection) doesn't
5956 recognize the color `"puke orange"', so the specification is
5959 4. So we continue looking for a specification matching the window's
5960 frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
5961 we call the instantiation method for colors. This time, the X
5962 server our window is on recognizes the color `moccasin', and so the
5963 instantiation method succeeds and returns a color instance.
5965 Here's another example, which implements something like GNU Emacs's
5966 "frame-local" variables.
5970 ;; There are probably better ways to write this macro
5971 ;; Heaven help you if VAR is a buffer-local; you will become very
5972 ;; confused. Probably should error on that.
5973 (defmacro define-frame-local-variable (var)
5974 "Make the unbound symbol VAR become a frame-local variable."
5975 (let ((val (if (boundp var) (symbol-value var) nil)))
5977 (setq ,var (make-specifier 'generic))
5978 (add-spec-to-specifier ,var ',val 'global))))
5980 ;; I'm not real happy about this terminology, how can `setq' be a defun?
5981 ;; But `frame-set' would have people writing "(frame-set 'foo value)".
5982 (defun frame-setq (var value &optional frame)
5983 "Set the local value of VAR to VALUE in FRAME.
5985 FRAME defaults to the selected frame."
5986 (and frame (not (framep frame))
5987 (error 'invalid-argument "FRAME must be a frame", frame))
5988 (add-spec-to-specifier var value (or frame (selected-frame))))
5990 (defun frame-value (var &optional frame)
5991 "Get the local value of VAR in FRAME.
5993 FRAME defaults to the selected frame."
5994 (and frame (not (framep frame))
5995 (error 'invalid-argument "FRAME must be a frame", frame))
5996 ;; this is not just a map from frames to values; it also falls back
5997 ;; to the global value
5998 (specifier-instance var (or frame (selected-frame))))
6001 (defun frame-set-default (var value)
6002 "Set the default value of frame-local variable VAR to VALUE."
6003 (add-spec-to-specifier var value 'global))
6005 (defun frame-get-default (var)
6006 "Get the default value of frame-local variable VAR."
6007 (car (specifier-specs var 'global)))
6009 Now you can execute the above definitions (eg, with `eval-last-sexp')
6010 and switch to `*scratch*' to play. Things will work differently if you
6011 already have a variable named `foo'.
6016 error--> Symbol's value as variable is void: foo
6018 (define-frame-local-variable foo)
6021 ;; the value of foo is a specifier, which is an opaque object;
6022 ;; you must use accessor functions to get values
6025 => #<generic-specifier global=(nil) 0x4f5cb>
6027 ;; since no frame-local value is set, the global value (which is the
6028 ;; constant `nil') is returned
6032 ;; get the default explicitly
6033 (frame-get-default foo)
6036 ;; get the whole specification list
6037 (specifier-specs foo 'global)
6040 ;; give foo a frame-local value
6042 (frame-setq foo 'bar)
6045 ;; access foo in several ways
6047 ;; Note that the print function for this kind of specifier only
6048 ;; gives you the global setting. To get the full list of specs for
6049 ;; debugging or study purposes, you must use specifier-specs or
6050 ;; specifier-spec-list.
6052 => #<generic-specifier global=(nil) 0x4f5cb>
6054 ;; get the whole specification list
6055 (specifier-specs foo)
6056 => ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))
6058 ;; get the frame-local value
6062 ;; get the default explicitly
6063 (frame-get-default foo)
6066 ;; Switch to another frame and evaluate:
6067 ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
6072 (specifier-specs foo)
6073 => ((#<x-frame "emacs" 0x28ec> (nil . baz))
6074 (#<x-frame "Message" 0x1bd66> (nil . bar))
6080 (frame-get-default foo)
6083 Note that since specifiers generalize both frame-local and
6084 buffer-local variables in a sensible way, XEmacs is not likely to put a
6085 high priority on implementing frame-local variables. In fact, some
6086 developers think that frame-local variables are evil for the same
6087 reason that buffer-local variables are evil: the declaration is both
6088 global and invisible. That is, you cannot tell whether a variable is
6089 "normal," buffer-local, or frame-local just by looking at it. So if
6090 you have namespace management problems, and some other Lisp package
6091 happens to use a variable name that you already declared frame- or
6092 buffer-local, weird stuff happens, and it is extremely hard to track
6096 File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Examples, Up: Specifiers
6098 Creating New Specifier Objects
6099 ==============================
6101 - Function: make-specifier type
6102 This function creates a new specifier.
6104 A specifier is an object that can be used to keep track of a
6105 property whose value can be per-buffer, per-window, per-frame, or
6106 per-device, and can further be restricted to a particular
6107 device-type or device-class. Specifiers are used, for example,
6108 for the various built-in properties of a face; this allows a face
6109 to have different values in different frames, buffers, etc. For
6110 more information, see `specifier-instance', `specifier-specs', and
6111 `add-spec-to-specifier'; or, for a detailed description of
6112 specifiers, including how they are instantiated over a particular
6113 domain (i.e. how their value in that domain is determined), see
6114 the chapter on specifiers in the XEmacs Lisp Reference Manual.
6116 TYPE specifies the particular type of specifier, and should be one
6117 of the symbols `generic', `integer', `natnum', `boolean', `color',
6118 `font', `image', `face-boolean', or `toolbar'.
6120 For more information on particular types of specifiers, see the
6121 functions `make-generic-specifier', `make-integer-specifier',
6122 `make-natnum-specifier', `make-boolean-specifier',
6123 `make-color-specifier', `make-font-specifier',
6124 `make-image-specifier', `make-face-boolean-specifier', and
6125 `make-toolbar-specifier'.
6127 - Function: make-specifier-and-init type spec-list &optional
6129 This function creates and initializes a new specifier.
6131 This is a convenience API combining `make-specifier' and
6132 `set-specifier' that allows you to create a specifier and add
6133 specs to it at the same time. TYPE specifies the specifier type.
6134 Allowed types are as for `make-specifier'.
6136 SPEC-LIST supplies the specification(s) to be added to the
6137 specifier. Any abbreviation of the full spec-list form accepted
6138 by `canonicalize-spec-list' may be used. However, if the optional
6139 argument DONT-CANONICALIZE is non-`nil', canonicalization is not
6140 performed, and the SPEC-LIST must already be in full form.
6142 - Function: make-integer-specifier spec-list
6143 Return a new `integer' specifier object with the given
6144 specification list. SPEC-LIST can be a list of specifications
6145 (each of which is a cons of a locale and a list of instantiators),
6146 a single instantiator, or a list of instantiators.
6148 Valid instantiators for integer specifiers are integers.
6150 - Function: make-boolean-specifier spec-list
6151 Return a new `boolean' specifier object with the given
6152 specification list. SPEC-LIST can be a list of specifications
6153 (each of which is a cons of a locale and a list of instantiators),
6154 a single instantiator, or a list of instantiators.
6156 Valid instantiators for boolean specifiers are `t' and `nil'.
6158 - Function: make-natnum-specifier spec-list
6159 Return a new `natnum' specifier object with the given specification
6160 list. SPEC-LIST can be a list of specifications (each of which is
6161 a cons of a locale and a list of instantiators), a single
6162 instantiator, or a list of instantiators.
6164 Valid instantiators for natnum specifiers are non-negative
6167 - Function: make-generic-specifier spec-list
6168 Return a new `generic' specifier object with the given
6169 specification list. SPEC-LIST can be a list of specifications
6170 (each of which is a cons of a locale and a list of instantiators),
6171 a single instantiator, or a list of instantiators.
6173 Valid instantiators for generic specifiers are all Lisp values.
6174 They are returned back unchanged when a specifier is instantiated.
6176 - Function: make-display-table-specifier spec-list
6177 Return a new `display-table' specifier object with the given spec
6178 list. SPEC-LIST can be a list of specifications (each of which is
6179 a cons of a locale and a list of instantiators), a single
6180 instantiator, or a list of instantiators.
6182 Valid instantiators for display-table specifiers are described in
6183 detail in the doc string for `current-display-table' (*note Active
6187 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
6189 Functions for Checking the Validity of Specifier Components
6190 ===========================================================
6192 - Function: valid-specifier-domain-p domain
6193 This function returns non-`nil' if DOMAIN is a valid specifier
6194 domain. A domain is used to instance a specifier (i.e. determine
6195 the specifier's value in that domain). Valid domains are a
6196 window, frame, or device. (`nil' is not valid.)
6198 - Function: valid-specifier-locale-p locale
6199 This function returns non-`nil' if LOCALE is a valid specifier
6200 locale. Valid locales are a device, a frame, a window, a buffer,
6201 and `global'. (`nil' is not valid.)
6203 - Function: valid-specifier-locale-type-p locale-type
6204 Given a specifier LOCALE-TYPE, this function returns non-`nil' if
6205 it is valid. Valid locale types are the symbols `global',
6206 `device', `frame', `window', and `buffer'. (Note, however, that in
6207 functions that accept either a locale or a locale type, `global'
6208 is considered an individual locale.)
6210 - Function: valid-specifier-type-p specifier-type
6211 Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
6212 valid. Valid types are `generic', `integer', `boolean', `color',
6213 `font', `image', `face-boolean', and `toolbar'.
6215 - Function: valid-specifier-tag-p tag
6216 This function returns non-`nil' if TAG is a valid specifier tag.
6218 - Function: valid-instantiator-p instantiator specifier-type
6219 This function returns non-`nil' if INSTANTIATOR is valid for
6222 - Function: valid-inst-list-p inst-list type
6223 This function returns non-`nil' if INST-LIST is valid for
6224 specifier type TYPE.
6226 - Function: valid-spec-list-p spec-list type
6227 This function returns non-`nil' if SPEC-LIST is valid for
6228 specifier type TYPE.
6230 - Function: check-valid-instantiator instantiator specifier-type
6231 This function signals an error if INSTANTIATOR is invalid for
6234 - Function: check-valid-inst-list inst-list type
6235 This function signals an error if INST-LIST is invalid for
6236 specifier type TYPE.
6238 - Function: check-valid-spec-list spec-list type
6239 This function signals an error if SPEC-LIST is invalid for
6240 specifier type TYPE.
6243 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
6245 Other Functions for Working with Specifications in a Specifier
6246 ==============================================================
6248 - Function: copy-specifier specifier &optional dest locale tag-set
6250 This function copies SPECIFIER to DEST, or creates a new one if
6253 If DEST is `nil' or omitted, a new specifier will be created and
6254 the specifications copied into it. Otherwise, the specifications
6255 will be copied into the existing specifier in DEST.
6257 If LOCALE is `nil' or the symbol `all', all specifications will be
6258 copied. If LOCALE is a particular locale, the specification for
6259 that particular locale will be copied. If LOCALE is a locale
6260 type, the specifications for all locales of that type will be
6261 copied. LOCALE can also be a list of locales, locale types,
6262 and/or `all'; this is equivalent to calling `copy-specifier' for
6263 each of the elements of the list. See `specifier-spec-list' for
6264 more information about LOCALE.
6266 Only instantiators where TAG-SET (a list of zero or more tags) is
6267 a subset of (or possibly equal to) the instantiator's tag set are
6268 copied. (The default value of `nil' is a subset of all tag sets,
6269 so in this case no instantiators will be screened out.) If EXACT-P
6270 is non-`nil', however, TAG-SET must be equal to an instantiator's
6271 tag set for the instantiator to be copied.
6273 Optional argument HOW-TO-ADD specifies what to do with existing
6274 specifications in DEST. If `nil', then whichever locales or locale
6275 types are copied will first be completely erased in DEST.
6276 Otherwise, it is the same as in `add-spec-to-specifier'.
6278 - Function: remove-specifier specifier &optional locale tag-set exact-p
6279 This function removes specification(s) for SPECIFIER.
6281 If LOCALE is a particular locale (a buffer, window, frame, device,
6282 or the symbol `global'), the specification for that locale will be
6285 If instead, LOCALE is a locale type (i.e. a symbol `buffer',
6286 `window', `frame', or `device'), the specifications for all
6287 locales of that type will be removed.
6289 If LOCALE is `nil' or the symbol `all', all specifications will be
6292 LOCALE can also be a list of locales, locale types, and/or `all';
6293 this is equivalent to calling `remove-specifier' for each of the
6294 elements in the list.
6296 Only instantiators where TAG-SET (a list of zero or more tags) is
6297 a subset of (or possibly equal to) the instantiator's tag set are
6298 removed. (The default value of `nil' is a subset of all tag sets,
6299 so in this case no instantiators will be screened out.) If EXACT-P
6300 is non-`nil', however, TAG-SET must be equal to an instantiator's
6301 tag set for the instantiator to be removed.
6303 - Function: map-specifier specifier func &optional locale maparg
6304 This function applies FUNC to the specification(s) for LOCALE in
6307 If optional LOCALE is a locale, FUNC will be called for that
6308 locale. If LOCALE is a locale type, FUNC will be mapped over all
6309 locales of that type. If LOCALE is `nil' or the symbol `all',
6310 FUNC will be mapped over all locales in SPECIFIER.
6312 Optional MS-MAPARG will be passed to MS-FUNC.
6314 FUNC is called with four arguments: the SPECIFIER, the locale
6315 being mapped over, the inst-list for that locale, and the optional
6316 MAPARG. If any invocation of FUNC returns non-`nil', the mapping
6317 will stop and the returned value becomes the value returned from
6318 `map-specifier'. Otherwise, `map-specifier' returns `nil'.
6320 - Function: specifier-locale-type-from-locale locale
6321 Given a specifier LOCALE, this function returns its type.
6324 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
6326 Faces and Window-System Objects
6327 *******************************
6331 * Faces:: Controlling the way text looks.
6332 * Fonts:: Controlling the typeface of text.
6333 * Colors:: Controlling the color of text and pixmaps.
6336 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
6341 A "face" is a named collection of graphical properties: font,
6342 foreground color, background color, background pixmap, optional
6343 underlining, and (on TTY devices) whether the text is to be highlighted,
6344 dimmed, blinking, or displayed in reverse video. Faces control the
6345 display of text on the screen. Every face has a name, which is a symbol
6346 such as `default' or `modeline'.
6348 Each built-in property of a face is controlled using a specifier,
6349 which allows it to have separate values in particular buffers, frames,
6350 windows, and devices and to further vary according to device type (X or
6351 TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
6352 for more information.
6354 The face named `default' is used for ordinary text. The face named
6355 `modeline' is used for displaying the modeline. The face named
6356 `highlight' is used for highlighted extents (*note Extents::). The
6357 faces named `left-margin' and `right-margin' are used for the left and
6358 right margin areas, respectively (*note Annotations::). The face named
6359 `zmacs-region' is used for the highlighted region between point and
6364 * Merging Faces:: How XEmacs decides which face to use
6366 * Basic Face Functions:: How to define and examine faces.
6367 * Face Properties:: How to access and modify a face's properties.
6368 * Face Convenience Functions:: Convenience functions for accessing
6369 particular properties of a face.
6370 * Other Face Display Functions:: Other functions pertaining to how a
6374 File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
6376 Merging Faces for Display
6377 -------------------------
6379 Here are all the ways to specify which face to use for display of text:
6381 * With defaults. Each frame has a "default face", which is used for
6382 all text that doesn't somehow specify another face. The face named
6383 `default' applies to the text area, while the faces `left-margin'
6384 and `right-margin' apply to the left and right margin areas.
6386 * With text properties. A character may have a `face' property; if
6387 so, it's displayed with that face. (Text properties are actually
6388 implemented in terms of extents.) *Note Text Properties::.
6390 * With extents. An extent may have a `face' property, which applies
6391 to all the text covered by the extent; in addition, if the
6392 `highlight' property is set, the `highlight' property applies when
6393 the mouse moves over the extent or if the extent is explicitly
6394 highlighted. *Note Extents::.
6396 * With annotations. Annotations that are inserted into a buffer can
6397 specify their own face. (Annotations are actually implemented in
6398 terms of extents.) *Note Annotations::.
6400 If these various sources together specify more than one face for a
6401 particular character, XEmacs merges the properties of the various faces
6402 specified. Extents, text properties, and annotations all use the same
6403 underlying representation (as extents). When multiple extents cover one
6404 character, an extent with higher priority overrides those with lower
6405 priority. *Note Extents::. If no extent covers a particular character,
6406 the `default' face is used.
6408 If a background pixmap is specified, it determines what will be
6409 displayed in the background of text characters. If the background
6410 pixmap is actually a pixmap, with its colors specified, those colors are
6411 used; if it is a bitmap, the face's foreground and background colors are
6415 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
6417 Basic Functions for Working with Faces
6418 --------------------------------------
6420 The properties a face can specify include the font, the foreground
6421 color, the background color, the background pixmap, the underlining,
6422 the display table, and (for TTY devices) whether the text is to be
6423 highlighted, dimmed, blinking, or displayed in reverse video. The face
6424 can also leave these unspecified, causing them to assume the value of
6425 the corresponding property of the `default' face.
6427 Here are the basic primitives for working with faces.
6429 - Function: make-face name &optional doc-string temporary
6430 This function defines and returns a new face named NAME, initially
6431 with all properties unspecified. It does nothing if there is
6432 already a face named NAME. Optional argument DOC-STRING specifies
6433 an explanatory string used for descriptive purposes. If optional
6434 argument TEMPORARY is non-`nil', the face will automatically
6435 disappear when there are no more references to it anywhere in text
6436 or Lisp code (otherwise, the face will continue to exist
6437 indefinitely even if it is not used).
6439 - Function: face-list &optional temporary
6440 This function returns a list of the names of all defined faces. If
6441 TEMPORARY is `nil', only the permanent faces are included. If it
6442 is `t', only the temporary faces are included. If it is any other
6443 non-`nil' value both permanent and temporary are included.
6445 - Function: facep object
6446 This function returns `t' if OBJECT is a face, else `nil'.
6448 - Function: copy-face old-face new-name &optional locale tag-set
6450 This function defines a new face named NEW-NAME which is a copy of
6451 the existing face named OLD-FACE. If there is already a face
6452 named NEW-NAME, then it alters the face to have the same
6453 properties as OLD-FACE.
6455 LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
6456 the old face rather than the whole face, and are as in
6457 `copy-specifier' (*note Specifiers::).
6460 File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
6465 You can examine and modify the properties of an existing face with the
6466 following functions.
6468 The following symbols have predefined meanings:
6471 The foreground color of the face.
6474 The background color of the face.
6477 The font used to display text covered by this face.
6480 The display table of the face.
6483 The pixmap displayed in the background of the face. Only used by
6487 Underline all text covered by this face.
6490 Highlight all text covered by this face. Only used by faces on TTY
6494 Dim all text covered by this face. Only used by faces on TTY
6498 Blink all text covered by this face. Only used by faces on TTY
6502 Reverse the foreground and background colors. Only used by faces
6506 Description of what the face's normal use is. NOTE: This is not a
6507 specifier, unlike all the other built-in properties, and cannot
6508 contain locale-specific values.
6510 - Function: set-face-property face property value &optional locale
6512 This function changes a property of a FACE.
6514 For built-in properties, the actual value of the property is a
6515 specifier and you cannot change this; but you can change the
6516 specifications within the specifier, and that is what this
6517 function will do. For user-defined properties, you can use this
6518 function to either change the actual value of the property or, if
6519 this value is a specifier, change the specifications within it.
6521 If PROPERTY is a built-in property, the specifications to be added
6522 to this property can be supplied in many different ways:
6524 If VALUE is a simple instantiator (e.g. a string naming a
6525 font or color) or a list of instantiators, then the
6526 instantiator(s) will be added as a specification of the
6527 property for the given LOCALE (which defaults to `global' if
6530 If VALUE is a list of specifications (each of which is a cons
6531 of a locale and a list of instantiators), then LOCALE must be
6532 `nil' (it does not make sense to explicitly specify a locale
6533 in this case), and specifications will be added as given.
6535 If VALUE is a specifier (as would be returned by
6536 `face-property' if no LOCALE argument is given), then some or
6537 all of the specifications in the specifier will be added to
6538 the property. In this case, the function is really
6539 equivalent to `copy-specifier' and LOCALE has the same
6540 semantics (if it is a particular locale, the specification
6541 for the locale will be copied; if a locale type,
6542 specifications for all locales of that type will be copied;
6543 if `nil' or `all', then all specifications will be copied).
6545 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
6546 `append', `remove-tag-set-prepend', `remove-tag-set-append',
6547 `remove-locale', `remove-locale-type', or `remove-all'. See
6548 `copy-specifier' and `add-spec-to-specifier' for a description of
6549 what each of these means. Most of the time, you do not need to
6550 worry about this argument; the default behavior usually is fine.
6552 In general, it is OK to pass an instance object (e.g. as returned
6553 by `face-property-instance') as an instantiator in place of an
6554 actual instantiator. In such a case, the instantiator used to
6555 create that instance object will be used (for example, if you set
6556 a font-instance object as the value of the `font' property, then
6557 the font name used to create that object will be used instead).
6558 If some cases, however, doing this conversion does not make sense,
6559 and this will be noted in the documentation for particular types
6560 of instance objects.
6562 If PROPERTY is not a built-in property, then this function will
6563 simply set its value if LOCALE is `nil'. However, if LOCALE is
6564 given, then this function will attempt to add VALUE as the
6565 instantiator for the given LOCALE, using `add-spec-to-specifier'.
6566 If the value of the property is not a specifier, it will
6567 automatically be converted into a `generic' specifier.
6569 - Function: remove-face-property face property &optional locale
6571 This function removes a property of a FACE.
6573 For built-in properties, this is analogous to `remove-specifier'.
6574 For more information, *Note Other Specification Functions::.
6576 When PROPERTY is not a built-in property, this function will just
6577 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
6578 is other than that, this function will attempt to remove VALUE as
6579 the instantiator for the given LOCALE with `remove-specifier'. If
6580 the value of the property is not a specifier, it will be converted
6581 into a `generic' specifier automatically.
6583 - Function: face-property face property &optional locale tag-set
6585 This function returns FACE's value of the given PROPERTY.
6587 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
6588 returned. For built-in properties, this will be a specifier
6589 object of a type appropriate to the property (e.g. a font or color
6590 specifier). For other properties, this could be anything.
6592 If LOCALE is supplied, then instead of returning the actual value,
6593 the specification(s) for the given locale or locale type will be
6594 returned. This will only work if the actual value of PROPERTY is
6595 a specifier (this will always be the case for built-in properties,
6596 but not or not may apply to user-defined properties). If the
6597 actual value of PROPERTY is not a specifier, this value will
6598 simply be returned regardless of LOCALE.
6600 The return value will be a list of instantiators (e.g. strings
6601 specifying a font or color name), or a list of specifications,
6602 each of which is a cons of a locale and a list of instantiators.
6603 Specifically, if LOCALE is a particular locale (a buffer, window,
6604 frame, device, or `global'), a list of instantiators for that
6605 locale will be returned. Otherwise, if LOCALE is a locale type
6606 (one of the symbols `buffer', `window', `frame', or `device'), the
6607 specifications for all locales of that type will be returned.
6608 Finally, if LOCALE is `all', the specifications for all locales of
6609 all types will be returned.
6611 The specifications in a specifier determine what the value of
6612 PROPERTY will be in a particular "domain" or set of circumstances,
6613 which is typically a particular Emacs window along with the buffer
6614 it contains and the frame and device it lies within. The value is
6615 derived from the instantiator associated with the most specific
6616 locale (in the order buffer, window, frame, device, and `global')
6617 that matches the domain in question. In other words, given a
6618 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
6619 will first be searched for a specification whose locale is the
6620 buffer contained within that window; then for a specification
6621 whose locale is the window itself; then for a specification whose
6622 locale is the frame that the window is contained within; etc. The
6623 first instantiator that is valid for the domain (usually this
6624 means that the instantiator is recognized by the device [i.e. the
6625 X server or TTY device] that the domain is on). The function
6626 `face-property-instance' actually does all this, and is used to
6627 determine how to display the face.
6629 - Function: face-property-instance face property &optional domain
6631 This function returns the instance of FACE's PROPERTY in the
6634 Under most circumstances, DOMAIN will be a particular window, and
6635 the returned instance describes how the specified property
6636 actually is displayed for that window and the particular buffer in
6637 it. Note that this may not be the same as how the property
6638 appears when the buffer is displayed in a different window or
6639 frame, or how the property appears in the same window if you
6640 switch to another buffer in that window; and in those cases, the
6641 returned instance would be different.
6643 The returned instance will typically be a color-instance,
6644 font-instance, or pixmap-instance object, and you can query it
6645 using the appropriate object-specific functions. For example, you
6646 could use `color-instance-rgb-components' to find out the RGB
6647 (red, green, and blue) components of how the `background' property
6648 of the `highlight' face is displayed in a particular window. The
6649 results might be different from the results you would get for
6650 another window (perhaps the user specified a different color for
6651 the frame that window is on; or perhaps the same color was
6652 specified but the window is on a different X server, and that X
6653 server has different RGB values for the color from this one).
6655 DOMAIN defaults to the selected window if omitted.
6657 DOMAIN can be a frame or device, instead of a window. The value
6658 returned for a such a domain is used in special circumstances when
6659 a more specific domain does not apply; for example, a frame value
6660 might be used for coloring a toolbar, which is conceptually
6661 attached to a frame rather than a particular window. The value is
6662 also useful in determining what the value would be for a
6663 particular window within the frame or device, if it is not
6664 overridden by a more specific specification.
6666 If PROPERTY does not name a built-in property, its value will
6667 simply be returned unless it is a specifier object, in which case
6668 it will be instanced using `specifier-instance'.
6670 Optional arguments DEFAULT and NO-FALLBACK are the same as in
6671 `specifier-instance'. *Note Specifiers::.
6674 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
6676 Face Convenience Functions
6677 --------------------------
6679 - Command: set-face-foreground face color &optional locale tag-set
6681 - Command: set-face-background face color &optional locale tag-set
6683 These functions set the foreground (respectively, background)
6684 color of face FACE to COLOR. The argument COLOR should be a
6685 string (the name of a color) or a color object as returned by
6686 `make-color' (*note Colors::).
6688 - Command: set-face-background-pixmap face pixmap &optional locale
6690 This function sets the background pixmap of face FACE to PIXMAP.
6691 The argument PIXMAP should be a string (the name of a bitmap or
6692 pixmap file; the directories listed in the variable
6693 `x-bitmap-file-path' will be searched) or a glyph object as
6694 returned by `make-glyph' (*note Glyphs::). The argument may also
6695 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
6696 are the size in pixels, and DATA is a string, containing the raw
6699 - Command: set-face-font face font &optional locale tag-set how-to-add
6700 This function sets the font of face FACE. The argument FONT
6701 should be a string or a font object as returned by `make-font'
6704 - Command: set-face-underline-p face underline-p &optional locale
6706 This function sets the underline property of face FACE.
6708 - Function: face-foreground face &optional locale tag-set exact-p
6709 - Function: face-background face &optional locale tag-set exact-p
6710 These functions return the foreground (respectively, background)
6711 color specifier of face FACE. *Note Colors::.
6713 - Function: face-background-pixmap face &optional locale tag-set
6715 This function return the background-pixmap glyph object of face
6718 - Function: face-font face &optional locale tag-set exact-p
6719 This function returns the font specifier of face FACE. (Note:
6720 This is not the same as the function `face-font' in FSF Emacs.)
6724 - Function: face-font-name face &optional domain
6725 This function returns the name of the font of face FACE, or `nil'
6726 if it is unspecified. This is basically equivalent to `(font-name
6727 (face-font FACE) DOMAIN)' except that it does not cause an error
6728 if FACE's font is `nil'. (This function is named `face-font' in
6731 - Function: face-underline-p face &optional locale
6732 This function returns the underline property of face FACE.
6734 - Function: face-foreground-instance face &optional domain
6735 - Function: face-background-instance face &optional domain
6736 These functions return the foreground (respectively, background)
6737 color specifier of face FACE. *Note Colors::.
6739 - Function: face-background-pixmap-instance face &optional domain
6740 This function return the background-pixmap glyph object of face
6743 - Function: face-font-instance face &optional domain
6744 This function returns the font specifier of face FACE. *Note
6748 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
6750 Other Face Display Functions
6751 ----------------------------
6753 - Command: invert-face face &optional locale
6754 Swap the foreground and background colors of face FACE. If the
6755 face doesn't specify both foreground and background, then its
6756 foreground and background are set to the default background and
6759 - Function: face-equal face1 face2 &optional domain
6760 This returns `t' if the faces FACE1 and FACE2 will display in the
6761 same way. DOMAIN is as in `face-property-instance'.
6763 - Function: face-differs-from-default-p face &optional domain
6764 This returns `t' if the face FACE displays differently from the
6765 default face. DOMAIN is as in `face-property-instance'.
6768 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
6773 This section describes how to work with font specifier and font
6774 instance objects, which encapsulate fonts in the window system.
6778 * Font Specifiers:: Specifying how a font will appear.
6779 * Font Instances:: What a font specifier gets instanced as.
6780 * Font Instance Names:: The name of a font instance.
6781 * Font Instance Size:: The size of a font instance.
6782 * Font Instance Characteristics:: Display characteristics of font instances.
6783 * Font Convenience Functions:: Convenience functions that automatically
6784 instance and retrieve the properties
6785 of a font specifier.
6788 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
6793 - Function: font-specifier-p object
6794 This predicate returns `t' if OBJECT is a font specifier, and
6797 - Function: make-font-specifier spec-list
6798 Return a new `font' specifier object with the given specification
6799 list. SPEC-LIST can be a list of specifications (each of which is
6800 a cons of a locale and a list of instantiators), a single
6801 instantiator, or a list of instantiators. *Note Specifiers::, for
6802 more information about specifiers.
6804 Valid instantiators for font specifiers are:
6806 * A string naming a font (e.g. under X this might be
6807 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
6808 14-point upright medium-weight Courier font).
6810 * A font instance (use that instance directly if the device
6811 matches, or use the string that generated it).
6813 * A vector of no elements (only on TTY's; this means to set no
6814 font at all, thus using the "natural" font of the terminal's
6817 * A vector of one element (a face to inherit from).
6820 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
6825 - Function: font-instance-p object
6826 This predicate returns `t' if OBJECT is a font instance, and `nil'
6829 - Function: make-font-instance name &optional device noerror
6830 This function creates a new font-instance object of the specified
6831 name. DEVICE specifies the device this object applies to and
6832 defaults to the selected device. An error is signalled if the
6833 font is unknown or cannot be allocated; however, if NOERROR is
6834 non-`nil', `nil' is simply returned in this case.
6836 The returned object is a normal, first-class lisp object. The way
6837 you "deallocate" the font is the way you deallocate any other lisp
6838 object: you drop all pointers to it and allow it to be garbage
6839 collected. When these objects are GCed, the underlying X data is
6840 deallocated as well.
6843 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
6848 - Function: list-fonts pattern &optional device
6849 This function returns a list of font names matching the given
6850 pattern. DEVICE specifies which device to search for names, and
6851 defaults to the currently selected device.
6853 - Function: font-instance-name font-instance
6854 This function returns the name used to allocate FONT-INSTANCE.
6856 - Function: font-instance-truename font-instance
6857 This function returns the canonical name of the given font
6858 instance. Font names are patterns which may match any number of
6859 fonts, of which the first found is used. This returns an
6860 unambiguous name for that font (but not necessarily its only
projects / chise / xemacs-chise.git.1 / blob