1 This is ../info/lispref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
55 43.8.5 Internals of the Kill Ring
56 ---------------------------------
58 The variable `kill-ring' holds the kill ring contents, in the form of a
59 list of strings. The most recent kill is always at the front of the
62 The `kill-ring-yank-pointer' variable points to a link in the kill
63 ring list, whose CAR is the text to yank next. We say it identifies
64 the "front" of the ring. Moving `kill-ring-yank-pointer' to a
65 different link is called "rotating the kill ring". We call the kill
66 ring a "ring" because the functions that move the yank pointer wrap
67 around from the end of the list to the beginning, or vice-versa.
68 Rotation of the kill ring is virtual; it does not change the value of
71 Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
72 whose values are normally lists. The word "pointer" in the name of the
73 `kill-ring-yank-pointer' indicates that the variable's purpose is to
74 identify one element of the list for use by the next yank command.
76 The value of `kill-ring-yank-pointer' is always `eq' to one of the
77 links in the kill ring list. The element it identifies is the CAR of
78 that link. Kill commands, which change the kill ring, also set this
79 variable to the value of `kill-ring'. The effect is to rotate the ring
80 so that the newly killed text is at the front.
82 Here is a diagram that shows the variable `kill-ring-yank-pointer'
83 pointing to the second entry in the kill ring `("some text" "a
84 different piece of text" "yet older text")'.
86 kill-ring kill-ring-yank-pointer
88 | ___ ___ ---> ___ ___ ___ ___
89 --> |___|___|------> |___|___|--> |___|___|--> nil
92 | | -->"yet older text"
94 | --> "a different piece of text"
98 This state of affairs might occur after `C-y' (`yank') immediately
99 followed by `M-y' (`yank-pop').
101 -- Variable: kill-ring
102 This variable holds the list of killed text sequences, most
103 recently killed first.
105 -- Variable: kill-ring-yank-pointer
106 This variable's value indicates which element of the kill ring is
107 at the "front" of the ring for yanking. More precisely, the value
108 is a tail of the value of `kill-ring', and its CAR is the kill
109 string that `C-y' should yank.
111 -- User Option: kill-ring-max
112 The value of this variable is the maximum length to which the kill
113 ring can grow, before elements are thrown away at the end. The
114 default value for `kill-ring-max' is 30.
117 File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
122 Most buffers have an "undo list", which records all changes made to the
123 buffer's text so that they can be undone. (The buffers that don't have
124 one are usually special-purpose buffers for which XEmacs assumes that
125 undoing is not useful.) All the primitives that modify the text in the
126 buffer automatically add elements to the front of the undo list, which
127 is in the variable `buffer-undo-list'.
129 -- Variable: buffer-undo-list
130 This variable's value is the undo list of the current buffer. A
131 value of `t' disables the recording of undo information.
133 Here are the kinds of elements an undo list can have:
136 This kind of element records a previous value of point. Ordinary
137 cursor motion does not get any sort of undo record, but deletion
138 commands use these entries to record where point was before the
142 This kind of element indicates how to delete text that was
143 inserted. Upon insertion, the text occupied the range START-END
147 This kind of element indicates how to reinsert text that was
148 deleted. The deleted text itself is the string TEXT. The place to
149 reinsert it is `(abs POSITION)'.
152 This kind of element indicates that an unmodified buffer became
153 modified. The elements HIGH and LOW are two integers, each
154 recording 16 bits of the visited file's modification time as of
155 when it was previously visited or saved. `primitive-undo' uses
156 those values to determine whether to mark the buffer as unmodified
157 once again; it does so only if the file's modification time
158 matches those numbers.
160 `(nil PROPERTY VALUE START . END)'
161 This kind of element records a change in a text property. Here's
162 how you might undo the change:
164 (put-text-property START END PROPERTY VALUE)
167 This element indicates where point was at an earlier time.
168 Undoing this element sets point to POSITION. Deletion normally
169 creates an element of this kind as well as a reinsertion element.
172 This element is a boundary. The elements between two boundaries
173 are called a "change group"; normally, each change group
174 corresponds to one keyboard command, and undo commands normally
175 undo an entire group as a unit.
177 -- Function: undo-boundary
178 This function places a boundary element in the undo list. The undo
179 command stops at such a boundary, and successive undo commands undo
180 to earlier and earlier boundaries. This function returns `nil'.
182 The editor command loop automatically creates an undo boundary
183 before each key sequence is executed. Thus, each undo normally
184 undoes the effects of one command. Self-inserting input
185 characters are an exception. The command loop makes a boundary
186 for the first such character; the next 19 consecutive
187 self-inserting input characters do not make boundaries, and then
188 the 20th does, and so on as long as self-inserting characters
191 All buffer modifications add a boundary whenever the previous
192 undoable change was made in some other buffer. This way, a
193 command that modifies several buffers makes a boundary in each
196 Calling this function explicitly is useful for splitting the
197 effects of a command into more than one unit. For example,
198 `query-replace' calls `undo-boundary' after each replacement, so
199 that the user can undo individual replacements one by one.
201 -- Function: primitive-undo count list
202 This is the basic function for undoing elements of an undo list.
203 It undoes the first COUNT elements of LIST, returning the rest of
204 LIST. You could write this function in Lisp, but it is convenient
207 `primitive-undo' adds elements to the buffer's undo list when it
208 changes the buffer. Undo commands avoid confusion by saving the
209 undo list value at the beginning of a sequence of undo operations.
210 Then the undo operations use and update the saved value. The new
211 elements added by undoing are not part of this saved value, so
212 they don't interfere with continuing to undo.
215 File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
217 43.10 Maintaining Undo Lists
218 ============================
220 This section describes how to enable and disable undo information for a
221 given buffer. It also explains how the undo list is truncated
222 automatically so it doesn't get too big.
224 Recording of undo information in a newly created buffer is normally
225 enabled to start with; but if the buffer name starts with a space, the
226 undo recording is initially disabled. You can explicitly enable or
227 disable undo recording with the following two functions, or by setting
228 `buffer-undo-list' yourself.
230 -- Command: buffer-enable-undo &optional buffer-or-name
231 This command enables recording undo information for buffer
232 BUFFER-OR-NAME, so that subsequent changes can be undone. If no
233 argument is supplied, then the current buffer is used. This
234 function does nothing if undo recording is already enabled in the
235 buffer. It returns `nil'.
237 In an interactive call, BUFFER-OR-NAME is the current buffer. You
238 cannot specify any other buffer.
240 -- Command: buffer-disable-undo &optional buffer
241 -- Command: buffer-flush-undo &optional buffer
242 This function discards the undo list of BUFFER, and disables
243 further recording of undo information. As a result, it is no
244 longer possible to undo either previous changes or any subsequent
245 changes. If the undo list of BUFFER is already disabled, this
246 function has no effect.
248 This function returns `nil'. It cannot be called interactively.
250 The name `buffer-flush-undo' is not considered obsolete, but the
251 preferred name `buffer-disable-undo' is new as of Emacs versions
254 As editing continues, undo lists get longer and longer. To prevent
255 them from using up all available memory space, garbage collection trims
256 them back to size limits you can set. (For this purpose, the "size" of
257 an undo list measures the cons cells that make up the list, plus the
258 strings of deleted text.) Two variables control the range of acceptable
259 sizes: `undo-limit' and `undo-strong-limit'.
261 -- Variable: undo-limit
262 This is the soft limit for the acceptable size of an undo list.
263 The change group at which this size is exceeded is the last one
266 -- Variable: undo-strong-limit
267 This is the upper limit for the acceptable size of an undo list.
268 The change group at which this size is exceeded is discarded
269 itself (along with all older change groups). There is one
270 exception: the very latest change group is never discarded no
271 matter how big it is.
274 File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
279 "Filling" means adjusting the lengths of lines (by moving the line
280 breaks) so that they are nearly (but no greater than) a specified
281 maximum width. Additionally, lines can be "justified", which means
282 inserting spaces to make the left and/or right margins line up
283 precisely. The width is controlled by the variable `fill-column'. For
284 ease of reading, lines should be no longer than 70 or so columns.
286 You can use Auto Fill mode (*note Auto Filling::) to fill text
287 automatically as you insert it, but changes to existing text may leave
288 it improperly filled. Then you must fill the text explicitly.
290 Most of the commands in this section return values that are not
291 meaningful. All the functions that do filling take note of the current
292 left margin, current right margin, and current justification style
293 (*note Margins::). If the current justification style is `none', the
294 filling functions don't actually do anything.
296 Several of the filling functions have an argument JUSTIFY. If it is
297 non-`nil', that requests some kind of justification. It can be `left',
298 `right', `full', or `center', to request a specific style of
299 justification. If it is `t', that means to use the current
300 justification style for this part of the text (see
301 `current-justification', below).
303 When you call the filling functions interactively, using a prefix
304 argument implies the value `full' for JUSTIFY.
306 -- Command: fill-paragraph justify
307 This command fills the paragraph at or after point. If JUSTIFY is
308 non-`nil', each line is justified as well. It uses the ordinary
309 paragraph motion commands to find paragraph boundaries. *Note
310 Paragraphs: (xemacs)Paragraphs.
312 -- Command: fill-region start end &optional justify
313 This command fills each of the paragraphs in the region from START
314 to END. It justifies as well if JUSTIFY is non-`nil'.
316 The variable `paragraph-separate' controls how to distinguish
317 paragraphs. *Note Standard Regexps::.
319 -- Command: fill-individual-paragraphs start end &optional justify
321 This command fills each paragraph in the region according to its
322 individual fill prefix. Thus, if the lines of a paragraph were
323 indented with spaces, the filled paragraph will remain indented in
326 The first two arguments, START and END, are the beginning and end
327 of the region to be filled. The third and fourth arguments,
328 JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
329 paragraphs are justified as well as filled. If MAIL-FLAG is
330 non-`nil', it means the function is operating on a mail message
331 and therefore should not fill the header lines.
333 Ordinarily, `fill-individual-paragraphs' regards each change in
334 indentation as starting a new paragraph. If
335 `fill-individual-varying-indent' is non-`nil', then only separator
336 lines separate paragraphs. That mode can handle indented
337 paragraphs with additional indentation on the first line.
339 -- User Option: fill-individual-varying-indent
340 This variable alters the action of `fill-individual-paragraphs' as
343 -- Command: fill-region-as-paragraph start end &optional justify
344 This command considers a region of text as a paragraph and fills
345 it. If the region was made up of many paragraphs, the blank lines
346 between paragraphs are removed. This function justifies as well
347 as filling when JUSTIFY is non-`nil'.
349 In an interactive call, any prefix argument requests justification.
351 In Adaptive Fill mode, which is enabled by default,
352 `fill-region-as-paragraph' on an indented paragraph when there is
353 no fill prefix uses the indentation of the second line of the
354 paragraph as the fill prefix.
356 -- Command: justify-current-line how eop nosqueeze
357 This command inserts spaces between the words of the current line
358 so that the line ends exactly at `fill-column'. It returns `nil'.
360 The argument HOW, if non-`nil' specifies explicitly the style of
361 justification. It can be `left', `right', `full', `center', or
362 `none'. If it is `t', that means to do follow specified
363 justification style (see `current-justification', below). `nil'
364 means to do full justification.
366 If EOP is non-`nil', that means do left-justification when
367 `current-justification' specifies full justification. This is used
368 for the last line of a paragraph; even if the paragraph as a whole
369 is fully justified, the last line should not be.
371 If NOSQUEEZE is non-`nil', that means do not change interior
374 -- User Option: default-justification
375 This variable's value specifies the style of justification to use
376 for text that doesn't specify a style with a text property. The
377 possible values are `left', `right', `full', `center', or `none'.
378 The default value is `left'.
380 -- Function: current-justification
381 This function returns the proper justification style to use for
382 filling the text around point.
384 -- Variable: fill-paragraph-function
385 This variable provides a way for major modes to override the
386 filling of paragraphs. If the value is non-`nil',
387 `fill-paragraph' calls this function to do the work. If the
388 function returns a non-`nil' value, `fill-paragraph' assumes the
389 job is done, and immediately returns that value.
391 The usual use of this feature is to fill comments in programming
392 language modes. If the function needs to fill a paragraph in the
393 usual way, it can do so as follows:
395 (let ((fill-paragraph-function nil))
396 (fill-paragraph arg))
398 -- Variable: use-hard-newlines
399 If this variable is non-`nil', the filling functions do not delete
400 newlines that have the `hard' text property. These "hard
401 newlines" act as paragraph separators.
404 File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
406 43.12 Margins for Filling
407 =========================
409 -- User Option: fill-prefix
410 This variable specifies a string of text that appears at the
411 beginning of normal text lines and should be disregarded when
412 filling them. Any line that fails to start with the fill prefix
413 is considered the start of a paragraph; so is any line that starts
414 with the fill prefix followed by additional whitespace. Lines
415 that start with the fill prefix but no additional whitespace are
416 ordinary text lines that can be filled together. The resulting
417 filled lines also start with the fill prefix.
419 The fill prefix follows the left margin whitespace, if any.
421 -- User Option: fill-column
422 This buffer-local variable specifies the maximum width of filled
423 lines. Its value should be an integer, which is a number of
424 columns. All the filling, justification and centering commands
425 are affected by this variable, including Auto Fill mode (*note
428 As a practical matter, if you are writing text for other people to
429 read, you should set `fill-column' to no more than 70. Otherwise
430 the line will be too long for people to read comfortably, and this
431 can make the text seem clumsy.
433 -- Variable: default-fill-column
434 The value of this variable is the default value for `fill-column'
435 in buffers that do not override it. This is the same as
436 `(default-value 'fill-column)'.
438 The default value for `default-fill-column' is 70.
440 -- Command: set-left-margin from to margin
441 This sets the `left-margin' property on the text from FROM to TO
442 to the value MARGIN. If Auto Fill mode is enabled, this command
443 also refills the region to fit the new margin.
445 -- Command: set-right-margin from to margin
446 This sets the `right-margin' property on the text from FROM to TO
447 to the value MARGIN. If Auto Fill mode is enabled, this command
448 also refills the region to fit the new margin.
450 -- Function: current-left-margin
451 This function returns the proper left margin value to use for
452 filling the text around point. The value is the sum of the
453 `left-margin' property of the character at the start of the
454 current line (or zero if none), and the value of the variable
457 -- Function: current-fill-column
458 This function returns the proper fill column value to use for
459 filling the text around point. The value is the value of the
460 `fill-column' variable, minus the value of the `right-margin'
461 property of the character after point.
463 -- Command: move-to-left-margin &optional n force
464 This function moves point to the left margin of the current line.
465 The column moved to is determined by calling the function
466 `current-left-margin'. If the argument N is non-`nil',
467 `move-to-left-margin' moves forward N-1 lines first.
469 If FORCE is non-`nil', that says to fix the line's indentation if
470 that doesn't match the left margin value.
472 -- Function: delete-to-left-margin &optional from to
473 This function removes left margin indentation from the text
474 between FROM and TO. The amount of indentation to delete is
475 determined by calling `current-left-margin'. In no case does this
476 function delete non-whitespace.
478 The arguments FROM and TO are optional; the default is the whole
481 -- Function: indent-to-left-margin
482 This is the default `indent-line-function', used in Fundamental
483 mode, Text mode, etc. Its effect is to adjust the indentation at
484 the beginning of the current line to the value specified by the
485 variable `left-margin'. This may involve either inserting or
488 -- Variable: left-margin
489 This variable specifies the base left margin column. In
490 Fundamental mode, <LFD> indents to this column. This variable
491 automatically becomes buffer-local when set in any fashion.
494 File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
499 Auto Fill mode is a minor mode that fills lines automatically as text
500 is inserted. This section describes the hook used by Auto Fill mode.
501 For a description of functions that you can call explicitly to fill and
502 justify existing text, see *Note Filling::.
504 Auto Fill mode also enables the functions that change the margins and
505 justification style to refill portions of the text. *Note Margins::.
507 -- Variable: auto-fill-function
508 The value of this variable should be a function (of no arguments)
509 to be called after self-inserting a space or a newline. It may be
510 `nil', in which case nothing special is done in that case.
512 The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
513 mode is enabled. That is a function whose sole purpose is to
514 implement the usual strategy for breaking a line.
516 In older Emacs versions, this variable was named
517 `auto-fill-hook', but since it is not called with the
518 standard convention for hooks, it was renamed to
519 `auto-fill-function' in version 19.
522 File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
527 The sorting functions described in this section all rearrange text in a
528 buffer. This is in contrast to the function `sort', which rearranges
529 the order of the elements of a list (*note Rearrangement::). The
530 values returned by these functions are not meaningful.
532 -- Function: sort-subr reverse nextrecfun endrecfun &optional
533 startkeyfun endkeyfun
534 This function is the general text-sorting routine that divides a
535 buffer into records and sorts them. Most of the commands in this
536 section use this function.
538 To understand how `sort-subr' works, consider the whole accessible
539 portion of the buffer as being divided into disjoint pieces called
540 "sort records". The records may or may not be contiguous; they may
541 not overlap. A portion of each sort record (perhaps all of it) is
542 designated as the sort key. Sorting rearranges the records in
543 order by their sort keys.
545 Usually, the records are rearranged in order of ascending sort key.
546 If the first argument to the `sort-subr' function, REVERSE, is
547 non-`nil', the sort records are rearranged in order of descending
550 The next four arguments to `sort-subr' are functions that are
551 called to move point across a sort record. They are called many
552 times from within `sort-subr'.
554 1. NEXTRECFUN is called with point at the end of a record. This
555 function moves point to the start of the next record. The
556 first record is assumed to start at the position of point
557 when `sort-subr' is called. Therefore, you should usually
558 move point to the beginning of the buffer before calling
561 This function can indicate there are no more sort records by
562 leaving point at the end of the buffer.
564 2. ENDRECFUN is called with point within a record. It moves
565 point to the end of the record.
567 3. STARTKEYFUN is called to move point from the start of a
568 record to the start of the sort key. This argument is
569 optional; if it is omitted, the whole record is the sort key.
570 If supplied, the function should either return a non-`nil'
571 value to be used as the sort key, or return `nil' to indicate
572 that the sort key is in the buffer starting at point. In the
573 latter case, ENDKEYFUN is called to find the end of the sort
576 4. ENDKEYFUN is called to move point from the start of the sort
577 key to the end of the sort key. This argument is optional.
578 If STARTKEYFUN returns `nil' and this argument is omitted (or
579 `nil'), then the sort key extends to the end of the record.
580 There is no need for ENDKEYFUN if STARTKEYFUN returns a
583 As an example of `sort-subr', here is the complete function
584 definition for `sort-lines':
586 ;; Note that the first two lines of doc string
587 ;; are effectively one line when viewed by a user.
588 (defun sort-lines (reverse start end)
589 "Sort lines in region alphabetically.
590 Called from a program, there are three arguments:
591 REVERSE (non-nil means reverse order),
592 and START and END (the region to sort)."
595 (narrow-to-region start end)
596 (goto-char (point-min))
601 Here `forward-line' moves point to the start of the next record,
602 and `end-of-line' moves point to the end of record. We do not pass
603 the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
604 is used as the sort key.
606 The `sort-paragraphs' function is very much the same, except that
607 its `sort-subr' call looks like this:
612 (skip-chars-forward "\n \t\f")))
615 -- Command: sort-regexp-fields reverse record-regexp key-regexp start
617 This command sorts the region between START and END alphabetically
618 as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
619 negative integer, then sorting is in reverse order.
621 Alphabetical sorting means that two sort keys are compared by
622 comparing the first characters of each, the second characters of
623 each, and so on. If a mismatch is found, it means that the sort
624 keys are unequal; the sort key whose character is less at the
625 point of first mismatch is the lesser sort key. The individual
626 characters are compared according to their numerical values.
627 Since Emacs uses the ASCII character set, the ordering in that set
628 determines alphabetical order.
630 The value of the RECORD-REGEXP argument specifies how to divide
631 the buffer into sort records. At the end of each record, a search
632 is done for this regular expression, and the text that matches it
633 is the next record. For example, the regular expression `^.+$',
634 which matches lines with at least one character besides a newline,
635 would make each such line into a sort record. *Note Regular
636 Expressions::, for a description of the syntax and meaning of
639 The value of the KEY-REGEXP argument specifies what part of each
640 record is the sort key. The KEY-REGEXP could match the whole
641 record, or only a part. In the latter case, the rest of the
642 record has no effect on the sorted order of records, but it is
643 carried along when the record moves to its new position.
645 The KEY-REGEXP argument can refer to the text matched by a
646 subexpression of RECORD-REGEXP, or it can be a regular expression
652 then the text matched by the DIGITth `\(...\)' parenthesis
653 grouping in RECORD-REGEXP is the sort key.
656 then the whole record is the sort key.
659 then `sort-regexp-fields' searches for a match for the regular
660 expression within the record. If such a match is found, it
661 is the sort key. If there is no match for KEY-REGEXP within
662 a record then that record is ignored, which means its
663 position in the buffer is not changed. (The other records
666 For example, if you plan to sort all the lines in the region by the
667 first word on each line starting with the letter `f', you should
668 set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'. The
669 resulting expression looks like this:
671 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
675 If you call `sort-regexp-fields' interactively, it prompts for
676 RECORD-REGEXP and KEY-REGEXP in the minibuffer.
678 -- Command: sort-lines reverse start end
679 This command alphabetically sorts lines in the region between
680 START and END. If REVERSE is non-`nil', the sort is in reverse
683 -- Command: sort-paragraphs reverse start end
684 This command alphabetically sorts paragraphs in the region between
685 START and END. If REVERSE is non-`nil', the sort is in reverse
688 -- Command: sort-pages reverse start end
689 This command alphabetically sorts pages in the region between
690 START and END. If REVERSE is non-`nil', the sort is in reverse
693 -- Command: sort-fields field start end
694 This command sorts lines in the region between START and END,
695 comparing them alphabetically by the FIELDth field of each line.
696 Fields are separated by whitespace and numbered starting from 1.
697 If FIELD is negative, sorting is by the -FIELDth field from the
698 end of the line. This command is useful for sorting tables.
700 -- Command: sort-numeric-fields field start end
701 This command sorts lines in the region between START and END,
702 comparing them numerically by the FIELDth field of each line. The
703 specified field must contain a number in each line of the region.
704 Fields are separated by whitespace and numbered starting from 1.
705 If FIELD is negative, sorting is by the -FIELDth field from the
706 end of the line. This command is useful for sorting tables.
708 -- Command: sort-columns reverse &optional start end
709 This command sorts the lines in the region between START and END,
710 comparing them alphabetically by a certain range of columns. The
711 column positions of START and END bound the range of columns to
714 If REVERSE is non-`nil', the sort is in reverse order.
716 One unusual thing about this command is that the entire line
717 containing position START, and the entire line containing position
718 END, are included in the region sorted.
720 Note that `sort-columns' uses the `sort' utility program, and so
721 cannot work properly on text containing tab characters. Use `M-x
722 `untabify'' to convert tabs to spaces before sorting.
725 File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
727 43.15 Counting Columns
728 ======================
730 The column functions convert between a character position (counting
731 characters from the beginning of the buffer) and a column position
732 (counting screen characters from the beginning of a line).
734 A character counts according to the number of columns it occupies on
735 the screen. This means control characters count as occupying 2 or 4
736 columns, depending upon the value of `ctl-arrow', and tabs count as
737 occupying a number of columns that depends on the value of `tab-width'
738 and on the column where the tab begins. *Note Usual Display::.
740 Column number computations ignore the width of the window and the
741 amount of horizontal scrolling. Consequently, a column value can be
742 arbitrarily high. The first (or leftmost) column is numbered 0.
744 -- Function: current-column &optional buffer
745 This function returns the horizontal position of point, measured in
746 columns, counting from 0 at the left margin.
748 This is calculated by adding together the widths of all the
749 displayed representations of the character between the start of
750 the previous line and point. (e.g. control characters will have a
751 width of 2 or 4, tabs will have a variable width.)
753 Ignores the finite width of frame displaying the buffer, which
754 means that this function may return values greater than
757 Whether the line is visible (if `selective-display' is t) has no
758 effect; however, ^M is treated as end of line when
759 `selective-display' is t.
761 If BUFFER is nil, the current buffer is assumed.
763 For an example of using `current-column', see the description of
764 `count-lines' in *Note Text Lines::.
766 -- Function: move-to-column column &optional force buffer
767 This function moves point to COLUMN in the current line. The
768 calculation of COLUMN takes into account the widths of the
769 displayed representations of the characters between the start of
772 If column COLUMN is beyond the end of the line, point moves to the
773 end of the line. If COLUMN is negative, point moves to the
774 beginning of the line.
776 If it is impossible to move to column COLUMN because that is in
777 the middle of a multicolumn character such as a tab, point moves
778 to the end of that character. However, if FORCE is non-`nil', and
779 COLUMN is in the middle of a tab, then `move-to-column' converts
780 the tab into spaces so that it can move precisely to column
781 COLUMN. Other multicolumn characters can cause anomalies despite
782 FORCE, since there is no way to split them.
784 The argument FORCE also has an effect if the line isn't long
785 enough to reach column COLUMN; in that case, unless the value of
786 FORCE is the special value `coerce', it says to add whitespace at
787 the end of the line to reach that column.
789 If COLUMN is not a non-negative integer, an error is signaled.
791 The return value is the column number actually moved to.
794 File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
799 The indentation functions are used to examine, move to, and change
800 whitespace that is at the beginning of a line. Some of the functions
801 can also change whitespace elsewhere on a line. Columns and indentation
802 count from zero at the left margin.
806 * Primitive Indent:: Functions used to count and insert indentation.
807 * Mode-Specific Indent:: Customize indentation for different modes.
808 * Region Indent:: Indent all the lines in a region.
809 * Relative Indent:: Indent the current line based on previous lines.
810 * Indent Tabs:: Adjustable, typewriter-like tab stops.
811 * Motion by Indent:: Move to first non-blank character.
814 File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation
816 43.16.1 Indentation Primitives
817 ------------------------------
819 This section describes the primitive functions used to count and insert
820 indentation. The functions in the following sections use these
823 -- Function: current-indentation &optional buffer
824 This function returns the indentation of the current line, which is
825 the horizontal position of the first nonblank character. If the
826 contents are entirely blank, then this is the horizontal position
827 of the end of the line.
829 -- Command: indent-to column &optional minimum buffer
830 This function indents from point with tabs and spaces until COLUMN
831 is reached. If MINIMUM is specified and non-`nil', then at least
832 that many spaces are inserted even if this requires going beyond
833 COLUMN. Otherwise the function does nothing if point is already
834 beyond COLUMN. The value is the column at which the inserted
835 indentation ends. If BUFFER is `nil', the current buffer is
838 -- User Option: indent-tabs-mode
839 If this variable is non-`nil', indentation functions can insert
840 tabs as well as spaces. Otherwise, they insert only spaces.
841 Setting this variable automatically makes it local to the current
845 File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
847 43.16.2 Indentation Controlled by Major Mode
848 --------------------------------------------
850 An important function of each major mode is to customize the <TAB> key
851 to indent properly for the language being edited. This section
852 describes the mechanism of the <TAB> key and how to control it. The
853 functions in this section return unpredictable values.
855 -- Variable: indent-line-function
856 This variable's value is the function to be used by <TAB> (and
857 various commands) to indent the current line. The command
858 `indent-according-to-mode' does no more than call this function.
860 In Lisp mode, the value is the symbol `lisp-indent-line'; in C
861 mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In
862 Fundamental mode, Text mode, and many other modes with no standard
863 for indentation, the value is `indent-to-left-margin' (which is the
866 -- Command: indent-according-to-mode
867 This command calls the function in `indent-line-function' to
868 indent the current line in a way appropriate for the current major
871 -- Command: indent-for-tab-command &optional prefix-arg
872 This command calls the function in `indent-line-function' to indent
873 the current line; except that if that function is
874 `indent-to-left-margin', it calls `insert-tab' instead. (That is
875 a trivial command that inserts a tab character.)
877 -- Command: newline-and-indent
878 This function inserts a newline, then indents the new line (the one
879 following the newline just inserted) according to the major mode.
881 It does indentation by calling the current `indent-line-function'.
882 In programming language modes, this is the same thing <TAB> does,
883 but in some text modes, where <TAB> inserts a tab,
884 `newline-and-indent' indents to the column specified by
887 -- Command: reindent-then-newline-and-indent
888 This command reindents the current line, inserts a newline at
889 point, and then reindents the new line (the one following the
890 newline just inserted).
892 This command does indentation on both lines according to the
893 current major mode, by calling the current value of
894 `indent-line-function'. In programming language modes, this is
895 the same thing <TAB> does, but in some text modes, where <TAB>
896 inserts a tab, `reindent-then-newline-and-indent' indents to the
897 column specified by `left-margin'.
900 File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
902 43.16.3 Indenting an Entire Region
903 ----------------------------------
905 This section describes commands that indent all the lines in the
906 region. They return unpredictable values.
908 -- Command: indent-region start end to-column
909 This command indents each nonblank line starting between START
910 (inclusive) and END (exclusive). If TO-COLUMN is `nil',
911 `indent-region' indents each nonblank line by calling the current
912 mode's indentation function, the value of `indent-line-function'.
914 If TO-COLUMN is non-`nil', it should be an integer specifying the
915 number of columns of indentation; then this function gives each
916 line exactly that much indentation, by either adding or deleting
919 If there is a fill prefix, `indent-region' indents each line by
920 making it start with the fill prefix.
922 -- Variable: indent-region-function
923 The value of this variable is a function that can be used by
924 `indent-region' as a short cut. You should design the function so
925 that it will produce the same results as indenting the lines of the
926 region one by one, but presumably faster.
928 If the value is `nil', there is no short cut, and `indent-region'
929 actually works line by line.
931 A short-cut function is useful in modes such as C mode and Lisp
932 mode, where the `indent-line-function' must scan from the
933 beginning of the function definition: applying it to each line
934 would be quadratic in time. The short cut can update the scan
935 information as it moves through the lines indenting them; this
936 takes linear time. In a mode where indenting a line individually
937 is fast, there is no need for a short cut.
939 `indent-region' with a non-`nil' argument TO-COLUMN has a
940 different meaning and does not use this variable.
942 -- Command: indent-rigidly start end count
943 This command indents all lines starting between START (inclusive)
944 and END (exclusive) sideways by COUNT columns. This "preserves
945 the shape" of the affected region, moving it as a rigid unit.
946 Consequently, this command is useful not only for indenting
947 regions of unindented text, but also for indenting regions of
950 For example, if COUNT is 3, this command adds 3 columns of
951 indentation to each of the lines beginning in the region specified.
953 In Mail mode, `C-c C-y' (`mail-yank-original') uses
954 `indent-rigidly' to indent the text copied from the message being
957 -- Command: indent-code-rigidly start end columns &optional
959 This is like `indent-rigidly', except that it doesn't alter lines
960 that start within strings or comments.
962 In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
963 the beginning of the line (if NOCHANGE-REGEXP is non-`nil').
966 File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
968 43.16.4 Indentation Relative to Previous Lines
969 ----------------------------------------------
971 This section describes two commands that indent the current line based
972 on the contents of previous lines.
974 -- Command: indent-relative &optional unindented-ok
975 This command inserts whitespace at point, extending to the same
976 column as the next "indent point" of the previous nonblank line.
977 An indent point is a non-whitespace character following
978 whitespace. The next indent point is the first one at a column
979 greater than the current column of point. For example, if point
980 is underneath and to the left of the first non-blank character of
981 a line of text, it moves to that column by inserting whitespace.
983 If the previous nonblank line has no next indent point (i.e., none
984 at a great enough column position), `indent-relative' either does
985 nothing (if UNINDENTED-OK is non-`nil') or calls
986 `tab-to-tab-stop'. Thus, if point is underneath and to the right
987 of the last column of a short line of text, this command ordinarily
988 moves point to the next tab stop by inserting whitespace.
990 The return value of `indent-relative' is unpredictable.
992 In the following example, point is at the beginning of the second
995 This line is indented twelve spaces.
996 -!-The quick brown fox jumped.
998 Evaluation of the expression `(indent-relative nil)' produces the
1001 This line is indented twelve spaces.
1002 -!-The quick brown fox jumped.
1004 In this example, point is between the `m' and `p' of `jumped':
1006 This line is indented twelve spaces.
1007 The quick brown fox jum-!-ped.
1009 Evaluation of the expression `(indent-relative nil)' produces the
1012 This line is indented twelve spaces.
1013 The quick brown fox jum -!-ped.
1015 -- Command: indent-relative-maybe
1016 This command indents the current line like the previous nonblank
1017 line. It calls `indent-relative' with `t' as the UNINDENTED-OK
1018 argument. The return value is unpredictable.
1020 If the previous nonblank line has no indent points beyond the
1021 current column, this command does nothing.
1024 File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation
1026 43.16.5 Adjustable "Tab Stops"
1027 ------------------------------
1029 This section explains the mechanism for user-specified "tab stops" and
1030 the mechanisms that use and set them. The name "tab stops" is used
1031 because the feature is similar to that of the tab stops on a
1032 typewriter. The feature works by inserting an appropriate number of
1033 spaces and tab characters to reach the next tab stop column; it does not
1034 affect the display of tab characters in the buffer (*note Usual
1035 Display::). Note that the <TAB> character as input uses this tab stop
1036 feature only in a few major modes, such as Text mode.
1038 -- Command: tab-to-tab-stop
1039 This command inserts spaces or tabs up to the next tab stop column
1040 defined by `tab-stop-list'. It searches the list for an element
1041 greater than the current column number, and uses that element as
1042 the column to indent to. It does nothing if no such element is
1045 -- User Option: tab-stop-list
1046 This variable is the list of tab stop columns used by
1047 `tab-to-tab-stops'. The elements should be integers in increasing
1048 order. The tab stop columns need not be evenly spaced.
1050 Use `M-x edit-tab-stops' to edit the location of tab stops
1054 File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
1056 43.16.6 Indentation-Based Motion Commands
1057 -----------------------------------------
1059 These commands, primarily for interactive use, act based on the
1060 indentation in the text.
1062 -- Command: back-to-indentation
1063 This command moves point to the first non-whitespace character in
1064 the current line (which is the line in which point is located).
1067 -- Command: backward-to-indentation arg
1068 This command moves point backward ARG lines and then to the first
1069 nonblank character on that line. It returns `nil'.
1071 -- Command: forward-to-indentation arg
1072 This command moves point forward ARG lines and then to the first
1073 nonblank character on that line. It returns `nil'.
1076 File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text
1081 The case change commands described here work on text in the current
1082 buffer. *Note Character Case::, for case conversion commands that work
1083 on strings and characters. *Note Case Tables::, for how to customize
1084 which characters are upper or lower case and how to convert them.
1086 -- Command: capitalize-region start end &optional buffer
1087 This function capitalizes all words in the region defined by START
1088 and END. To capitalize means to convert each word's first
1089 character to upper case and convert the rest of each word to lower
1090 case. The function returns `nil'.
1092 If one end of the region is in the middle of a word, the part of
1093 the word within the region is treated as an entire word.
1095 When `capitalize-region' is called interactively, START and END
1096 are point and the mark, with the smallest first.
1098 ---------- Buffer: foo ----------
1099 This is the contents of the 5th foo.
1100 ---------- Buffer: foo ----------
1102 (capitalize-region 1 44)
1105 ---------- Buffer: foo ----------
1106 This Is The Contents Of The 5th Foo.
1107 ---------- Buffer: foo ----------
1109 -- Command: downcase-region start end &optional buffer
1110 This function converts all of the letters in the region defined by
1111 START and END to lower case. The function returns `nil'.
1113 When `downcase-region' is called interactively, START and END are
1114 point and the mark, with the smallest first.
1116 -- Command: upcase-region start end &optional buffer
1117 This function converts all of the letters in the region defined by
1118 START and END to upper case. The function returns `nil'.
1120 When `upcase-region' is called interactively, START and END are
1121 point and the mark, with the smallest first.
1123 -- Command: capitalize-word count &optional buffer
1124 This function capitalizes COUNT words after point, moving point
1125 over as it does. To capitalize means to convert each word's first
1126 character to upper case and convert the rest of each word to lower
1127 case. If COUNT is negative, the function capitalizes the -COUNT
1128 previous words but does not move point. The value is `nil'.
1130 If point is in the middle of a word, the part of the word before
1131 point is ignored when moving forward. The rest is treated as an
1134 When `capitalize-word' is called interactively, COUNT is set to
1135 the numeric prefix argument.
1137 -- Command: downcase-word count &optional buffer
1138 This function converts the COUNT words after point to all lower
1139 case, moving point over as it does. If COUNT is negative, it
1140 converts the -COUNT previous words but does not move point. The
1143 When `downcase-word' is called interactively, COUNT is set to the
1144 numeric prefix argument.
1146 -- Command: upcase-word count &optional buffer
1147 This function converts the COUNT words after point to all upper
1148 case, moving point over as it does. If COUNT is negative, it
1149 converts the -COUNT previous words but does not move point. The
1152 When `upcase-word' is called interactively, COUNT is set to the
1153 numeric prefix argument.
1156 File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text
1158 43.18 Text Properties
1159 =====================
1161 Text properties are an alternative interface to extents (*note
1162 Extents::), and are built on top of them. They are useful when you
1163 want to view textual properties as being attached to the characters
1164 themselves rather than to intervals of characters. The text property
1165 interface is compatible with FSF Emacs.
1167 Each character position in a buffer or a string can have a "text
1168 property list", much like the property list of a symbol (*note Property
1169 Lists::). The properties belong to a particular character at a
1170 particular place, such as, the letter `T' at the beginning of this
1171 sentence or the first `o' in `foo'--if the same character occurs in two
1172 different places, the two occurrences generally have different
1175 Each property has a name and a value. Both of these can be any Lisp
1176 object, but the name is normally a symbol. The usual way to access the
1177 property list is to specify a name and ask what value corresponds to it.
1179 Note that FSF Emacs also looks at the `category' property to find
1180 defaults for text properties. We consider this too bogus to implement.
1182 Copying text between strings and buffers preserves the properties
1183 along with the characters; this includes such diverse functions as
1184 `substring', `insert', and `buffer-substring'.
1188 * Examining Properties:: Looking at the properties of one character.
1189 * Changing Properties:: Setting the properties of a range of text.
1190 * Property Search:: Searching for where a property changes value.
1191 * Special Properties:: Particular properties with special meanings.
1192 * Saving Properties:: Saving text properties in files, and reading
1194 * Fields:: Emacs-compatible text fields.
1197 File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
1199 43.18.1 Examining Text Properties
1200 ---------------------------------
1202 The simplest way to examine text properties is to ask for the value of
1203 a particular property of a particular character. For that, use
1204 `get-text-property'. Use `text-properties-at' to get the entire
1205 property list of a character. *Note Property Search::, for functions
1206 to examine the properties of a number of characters at once.
1208 These functions handle both strings and buffers. (Keep in mind that
1209 positions in a string start from 0, whereas positions in a buffer start
1212 -- Function: get-text-property pos prop &optional object at-flag
1213 This function returns the value of the PROP property of the
1214 character after position POS in OBJECT (a buffer or string). The
1215 argument OBJECT is optional and defaults to the current buffer.
1217 -- Function: get-char-property pos prop &optional object at-flag
1218 This function is like `get-text-property', except that it checks
1219 all extents, not just text-property extents.
1222 -- Function: text-properties-at position &optional object
1223 This function returns the entire property list of the character at
1224 POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
1225 defaults to the current buffer.
1227 -- Variable: default-text-properties
1228 This variable holds a property list giving default values for text
1229 properties. Whenever a character does not specify a value for a
1230 property, the value stored in this list is used instead. Here is
1233 (setq default-text-properties '(foo 69))
1234 ;; Make sure character 1 has no properties of its own.
1235 (set-text-properties 1 2 nil)
1236 ;; What we get, when we ask, is the default value.
1237 (get-text-property 1 'foo)
1241 File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
1243 43.18.2 Changing Text Properties
1244 --------------------------------
1246 The primitives for changing properties apply to a specified range of
1247 text. The function `set-text-properties' (see end of section) sets the
1248 entire property list of the text in that range; more often, it is
1249 useful to add, change, or delete just certain properties specified by
1252 Since text properties are considered part of the buffer's contents,
1253 and can affect how the buffer looks on the screen, any change in the
1254 text properties is considered a buffer modification. Buffer text
1255 property changes are undoable (*note Undo::).
1257 -- Function: put-text-property start end prop value &optional object
1258 This function sets the PROP property to VALUE for the text between
1259 START and END in the string or buffer OBJECT. If OBJECT is `nil',
1260 it defaults to the current buffer.
1262 -- Function: add-text-properties start end props &optional object
1263 This function modifies the text properties for the text between
1264 START and END in the string or buffer OBJECT. If OBJECT is `nil',
1265 it defaults to the current buffer.
1267 The argument PROPS specifies which properties to change. It
1268 should have the form of a property list (*note Property Lists::):
1269 a list whose elements include the property names followed
1270 alternately by the corresponding values.
1272 The return value is `t' if the function actually changed some
1273 property's value; `nil' otherwise (if PROPS is `nil' or its values
1274 agree with those in the text).
1276 For example, here is how to set the `comment' and `face'
1277 properties of a range of text:
1279 (add-text-properties START END
1280 '(comment t face highlight))
1282 -- Function: remove-text-properties start end props &optional object
1283 This function deletes specified text properties from the text
1284 between START and END in the string or buffer OBJECT. If OBJECT
1285 is `nil', it defaults to the current buffer.
1287 The argument PROPS specifies which properties to delete. It
1288 should have the form of a property list (*note Property Lists::):
1289 a list whose elements are property names alternating with
1290 corresponding values. But only the names matter--the values that
1291 accompany them are ignored. For example, here's how to remove the
1294 (remove-text-properties START END '(face nil))
1296 The return value is `t' if the function actually changed some
1297 property's value; `nil' otherwise (if PROPS is `nil' or if no
1298 character in the specified text had any of those properties).
1300 -- Function: set-text-properties start end props &optional object
1301 This function completely replaces the text property list for the
1302 text between START and END in the string or buffer OBJECT. If
1303 OBJECT is `nil', it defaults to the current buffer.
1305 The argument PROPS is the new property list. It should be a list
1306 whose elements are property names alternating with corresponding
1309 After `set-text-properties' returns, all the characters in the
1310 specified range have identical properties.
1312 If PROPS is `nil', the effect is to get rid of all properties from
1313 the specified range of text. Here's an example:
1315 (set-text-properties START END nil)
1317 See also the function `buffer-substring-without-properties' (*note
1318 Buffer Contents::) which copies text from the buffer but does not copy
1322 File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
1324 43.18.3 Property Search Functions
1325 ---------------------------------
1327 In typical use of text properties, most of the time several or many
1328 consecutive characters have the same value for a property. Rather than
1329 writing your programs to examine characters one by one, it is much
1330 faster to process chunks of text that have the same property value.
1332 Here are functions you can use to do this. They use `eq' for
1333 comparing property values. In all cases, OBJECT defaults to the
1336 For high performance, it's very important to use the LIMIT argument
1337 to these functions, especially the ones that search for a single
1338 property--otherwise, they may spend a long time scanning to the end of
1339 the buffer, if the property you are interested in does not change.
1341 Remember that a position is always between two characters; the
1342 position returned by these functions is between two characters with
1343 different properties.
1345 -- Function: next-property-change pos &optional object limit
1346 The function scans the text forward from position POS in the
1347 string or buffer OBJECT till it finds a change in some text
1348 property, then returns the position of the change. In other
1349 words, it returns the position of the first character beyond POS
1350 whose properties are not identical to those of the character just
1353 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
1354 there is no property change before that point,
1355 `next-property-change' returns LIMIT.
1357 The value is `nil' if the properties remain unchanged all the way
1358 to the end of OBJECT and LIMIT is `nil'. If the value is
1359 non-`nil', it is a position greater than or equal to POS. The
1360 value equals POS only when LIMIT equals POS.
1362 Here is an example of how to scan the buffer by chunks of text
1363 within which all properties are constant:
1366 (let ((plist (text-properties-at (point)))
1368 (or (next-property-change (point) (current-buffer))
1370 Process text from point to NEXT-CHANGE...
1371 (goto-char next-change)))
1373 -- Function: next-single-property-change pos prop &optional object
1375 The function scans the text forward from position POS in the
1376 string or buffer OBJECT till it finds a change in the PROP
1377 property, then returns the position of the change. In other
1378 words, it returns the position of the first character beyond POS
1379 whose PROP property differs from that of the character just after
1382 If LIMIT is non-`nil', then the scan ends at position LIMIT. If
1383 there is no property change before that point,
1384 `next-single-property-change' returns LIMIT.
1386 The value is `nil' if the property remains unchanged all the way to
1387 the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
1388 it is a position greater than or equal to POS; it equals POS only
1389 if LIMIT equals POS.
1391 -- Function: previous-property-change pos &optional object limit
1392 This is like `next-property-change', but scans backward from POS
1393 instead of forward. If the value is non-`nil', it is a position
1394 less than or equal to POS; it equals POS only if LIMIT equals POS.
1396 -- Function: previous-single-property-change pos prop &optional object
1398 This is like `next-single-property-change', but scans backward from
1399 POS instead of forward. If the value is non-`nil', it is a
1400 position less than or equal to POS; it equals POS only if LIMIT
1403 -- Function: text-property-any start end prop value &optional object
1404 This function returns non-`nil' if at least one character between
1405 START and END has a property PROP whose value is VALUE. More
1406 precisely, it returns the position of the first such character.
1407 Otherwise, it returns `nil'.
1409 The optional fifth argument, OBJECT, specifies the string or
1410 buffer to scan. Positions are relative to OBJECT. The default
1411 for OBJECT is the current buffer.
1413 -- Function: text-property-not-all start end prop value &optional
1415 This function returns non-`nil' if at least one character between
1416 START and END has a property PROP whose value differs from VALUE.
1417 More precisely, it returns the position of the first such
1418 character. Otherwise, it returns `nil'.
1420 The optional fifth argument, OBJECT, specifies the string or
1421 buffer to scan. Positions are relative to OBJECT. The default
1422 for OBJECT is the current buffer.
1425 File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
1427 43.18.4 Properties with Special Meanings
1428 ----------------------------------------
1430 The predefined properties are the same as those for extents. *Note
1431 Extent Properties::.
1434 File: lispref.info, Node: Saving Properties, Next: Fields, Prev: Special Properties, Up: Text Properties
1436 43.18.5 Saving Text Properties in Files
1437 ---------------------------------------
1439 You can save text properties in files, and restore text properties when
1440 inserting the files, using these two hooks:
1442 -- Variable: write-region-annotate-functions
1443 This variable's value is a list of functions for `write-region' to
1444 run to encode text properties in some fashion as annotations to
1445 the text being written in the file. *Note Writing to Files::.
1447 Each function in the list is called with two arguments: the start
1448 and end of the region to be written. These functions should not
1449 alter the contents of the buffer. Instead, they should return
1450 lists indicating annotations to write in the file in addition to
1451 the text in the buffer.
1453 Each function should return a list of elements of the form
1454 `(POSITION . STRING)', where POSITION is an integer specifying the
1455 relative position in the text to be written, and STRING is the
1456 annotation to add there.
1458 Each list returned by one of these functions must be already
1459 sorted in increasing order by POSITION. If there is more than one
1460 function, `write-region' merges the lists destructively into one
1463 When `write-region' actually writes the text from the buffer to the
1464 file, it intermixes the specified annotations at the corresponding
1465 positions. All this takes place without modifying the buffer.
1467 -- Variable: after-insert-file-functions
1468 This variable holds a list of functions for `insert-file-contents'
1469 to call after inserting a file's contents. These functions should
1470 scan the inserted text for annotations, and convert them to the
1471 text properties they stand for.
1473 Each function receives one argument, the length of the inserted
1474 text; point indicates the start of that text. The function should
1475 scan that text for annotations, delete them, and create the text
1476 properties that the annotations specify. The function should
1477 return the updated length of the inserted text, as it stands after
1478 those changes. The value returned by one function becomes the
1479 argument to the next function.
1481 These functions should always return with point at the beginning of
1484 The intended use of `after-insert-file-functions' is for converting
1485 some sort of textual annotations into actual text properties. But
1486 other uses may be possible.
1488 We invite users to write Lisp programs to store and retrieve text
1489 properties in files, using these hooks, and thus to experiment with
1490 various data formats and find good ones. Eventually we hope users will
1491 produce good, general extensions we can install in Emacs.
1493 We suggest not trying to handle arbitrary Lisp objects as property
1494 names or property values--because a program that general is probably
1495 difficult to write, and slow. Instead, choose a set of possible data
1496 types that are reasonably flexible, and not too hard to encode.
1498 *Note Format Conversion::, for a related feature.
1501 File: lispref.info, Node: Fields, Prev: Saving Properties, Up: Text Properties
1506 Emacs supplies a notion of a _text field_, which is a region of text
1507 where every character has the same value of the `field' property. It
1508 is used to identify regions of a buffer used for communicating with an
1509 external process, for example. XEmacs supplies a compatible interface.
1510 In XEmacs, the `field' property can be set as either an extent
1511 property or a text property, mirroring the Emacs capability of using
1512 either overlays or text properties.
1514 The field manipulating functions take a buffer position as the
1515 field-identifying argument, defaulting to point. This really means the
1516 field containing that buffer position. Consecutive buffer positions
1517 with no `field' property are considered an "empty" field. There is
1518 some ambiguity when a specified buffer position falls at the very
1519 beginning or the very end of a field: does it belong to the preceding or
1520 the following field? The answer depends on the openness or closedness
1521 of the corresponding extents (*note Extent Endpoints::). A buffer
1522 position corresponds to the field whose property would be inherited by a
1523 character inserted at that position. If the buffer position is between
1524 an end-open and a start-open extent, then it corresponds to an empty
1525 field at that position, since an inserted character will belong to
1528 -- Variable: inhibit-field-text-motion
1529 This variable controls whether the text motion commands notice
1530 fields or not. When it is nil (the default), commands such as
1531 beginning-of-line will try to move only within fields.
1533 -- Function: make-field value from to &optional buffer
1534 There is no Emacs counterpart to this function. The default open
1535 and closedness of extents in XEmacs is opposite to the default for
1536 Emacs overlays. Hence, fields based on extents in XEmacs behave
1537 differently from the equivalent fields based on overlays in Emacs.
1538 This function creates a field with value VALUE over the region
1539 FROM to TO in BUFFER, which defaults to the current buffer, with
1540 the default Emacs open and closedness.
1542 -- Function: find-field &optional pos merge-at-boundary beg-limit
1544 There is no (Lisp-visible) Emacs counterpart to this function. It
1545 is the workhorse for the other functions. It returns a dotted pair
1546 `(start . stop)' holding the endpoints of the field matching a
1547 specification. If POS is non-`nil', it specifies a buffer
1548 position whose enclosing field should be found; otherwise, the
1549 value of point is used.
1551 If MERGE-AT-BOUNDARY is non-`nil', then two changes are made to
1552 the search algorithm. First, if POS is at the very first position
1553 of a field, then the beginning of the previous field is returned
1554 instead of the beginning of POS's field. Second, if the value of
1555 the `field' property at POS is the symbol `boundary', then the
1556 beginning of the field before the boundary field and the end of
1557 the field after the boundary field are returned.
1559 If BEG-LIMIT is a buffer position, and the start position that
1560 would be returned is less than BEG-LIMIT, then BEG-LIMIT is
1561 returned instead. Likewise, if END-LIMIT is a buffer position,
1562 and the stop position that would be returned is greater than
1563 END-LIMIT, then END-LIMIT is returned instead.
1565 -- Function: delete-field &optional pos
1566 Delete the text of the field at POS.
1568 -- Function: field-string &optional pos
1569 Return the contents of the field at POS as a string.
1571 -- Function: field-string-no-properties &optional pos
1572 Return the contents of the field at POS as a string, without text
1575 -- Function: field-beginning &optional pos escape-from-edge limit
1576 Return the beginning of the field at POS. If ESCAPE-FROM-EDGE is
1577 non-nil and POS is at the beginning of a field, then the beginning
1578 of the field that ends at POS is returned instead. If LIMIT is a
1579 buffer position and the returned value would be less than LIMIT,
1580 then LIMIT is returned instead.
1582 -- Function: field-end &optional pos escape-from-edge limit
1583 Return the end of the field at POS. If ESCAPE-FROM-EDGE is
1584 non-nil and POS is at the end of a field, then the end of the
1585 field that begins at POS is returned instead. If LIMIT is a
1586 buffer position and the returned value would be greater than
1587 LIMIT, then LIMIT is returned instead.
1589 -- Function: constrain-to-field new-pos old-pos &optional
1590 escape-from-edge only-in-line inhibit-capture-property
1591 Return the position closest to NEW-POS that is in the same field
1592 as OLD-POS. If NEW-POS is `nil', then the value of point is used
1593 instead _and_ point is set to the value that is returned.
1595 If ESCAPE-FROM-EDGE is non-`nil' and OLD-POS is at the boundary of
1596 two fields, then the two adjacent fields are considered one field.
1597 Furthermore, if NEW-POS is in a field whose `field' property is
1598 the symbol `boundary', then the preceding field, the boundary
1599 field, and the following field are considered one field.
1601 If ONLY-IN-LINE is non-`nil' and the returned position would be on
1602 a different line than NEW-POS, return NEW-POS instead.
1604 If INHIBIT-CAPTURE-PROPERTY is non-`nil' and the character at
1605 OLD-POS has a property of the same name as the value of
1606 INHIBIT-CAPTURE-PROPERTY, then all field boundaries are ignored;
1607 i.e., NEW-POS is returned.
1609 If INHIBIT-FIELD-TEXT-MOTION is non-`nil', then all field
1610 boundaries are ignored and this function always returns NEW-POS.
1613 File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
1615 43.19 Substituting for a Character Code
1616 =======================================
1618 The following functions replace characters within a specified region
1619 based on their character codes.
1621 -- Function: subst-char-in-region start end old-char new-char
1623 This function replaces all occurrences of the character OLD-CHAR
1624 with the character NEW-CHAR in the region of the current buffer
1625 defined by START and END.
1627 If NOUNDO is non-`nil', then `subst-char-in-region' does not
1628 record the change for undo and does not mark the buffer as
1629 modified. This feature is used for controlling selective display
1630 (*note Selective Display::).
1632 `subst-char-in-region' does not move point and returns `nil'.
1634 ---------- Buffer: foo ----------
1635 This is the contents of the buffer before.
1636 ---------- Buffer: foo ----------
1638 (subst-char-in-region 1 20 ?i ?X)
1641 ---------- Buffer: foo ----------
1642 ThXs Xs the contents of the buffer before.
1643 ---------- Buffer: foo ----------
1645 -- Function: translate-region start end table
1646 This function applies a translation table to the characters in the
1647 buffer between positions START and END. The translation table
1648 TABLE can be either a string, a vector, or a char-table.
1650 If TABLE is a string, its Nth element is the mapping for the
1651 character with code N.
1653 If TABLE is a vector, its Nth element is the mapping for character
1654 with code N. Legal mappings are characters, strings, or `nil'
1655 (meaning don't replace.)
1657 If TABLE is a char-table, its elements describe the mapping
1658 between characters and their replacements. The char-table should
1659 be of type `char' or `generic'.
1661 When the TABLE is a string or vector and its length is less than
1662 the total number of characters (256 without Mule), any characters
1663 with codes larger than the length of TABLE are not altered by the
1666 The return value of `translate-region' is the number of characters
1667 that were actually changed by the translation. This does not
1668 count characters that were mapped into themselves in the
1671 *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
1672 to be a string. This is still the case in FSF Emacs.
1674 The following example creates a char-table that is passed to
1675 `translate-region', which translates character `a' to `the letter
1676 a', removes character `b', and translates character `c' to newline.
1678 ---------- Buffer: foo ----------
1679 Here is a sentence in the buffer.
1680 ---------- Buffer: foo ----------
1682 (let ((table (make-char-table 'generic)))
1683 (put-char-table ?a "the letter a" table)
1684 (put-char-table ?b "" table)
1685 (put-char-table ?c ?\n table)
1686 (translate-region (point-min) (point-max) table))
1689 ---------- Buffer: foo ----------
1690 Here is the letter a senten
1692 ---------- Buffer: foo ----------
1695 File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
1700 A register is a sort of variable used in XEmacs editing that can hold a
1701 marker, a string, a rectangle, a window configuration (of one frame), or
1702 a frame configuration (of all frames). Each register is named by a
1703 single character. All characters, including control and meta characters
1704 (but with the exception of `C-g'), can be used to name registers.
1705 Thus, there are 255 possible registers. A register is designated in
1706 Emacs Lisp by a character that is its name.
1708 The functions in this section return unpredictable values unless
1711 -- Variable: register-alist
1712 This variable is an alist of elements of the form `(NAME .
1713 CONTENTS)'. Normally, there is one element for each XEmacs
1714 register that has been used.
1716 The object NAME is a character (an integer) identifying the
1717 register. The object CONTENTS is a string, marker, or list
1718 representing the register contents. A string represents text
1719 stored in the register. A marker represents a position. A list
1720 represents a rectangle; its elements are strings, one per line of
1723 -- Function: get-register register
1724 This function returns the contents of the register REGISTER, or
1725 `nil' if it has no contents.
1727 -- Function: set-register register value
1728 This function sets the contents of register REGISTER to VALUE. A
1729 register can be set to any value, but the other register functions
1730 expect only certain data types. The return value is VALUE.
1732 -- Command: view-register register
1733 This command displays what is contained in register REGISTER.
1735 -- Command: insert-register register &optional beforep
1736 This command inserts contents of register REGISTER into the current
1739 Normally, this command puts point before the inserted text, and the
1740 mark after it. However, if the optional second argument BEFOREP
1741 is non-`nil', it puts the mark before and point after. You can
1742 pass a non-`nil' second argument BEFOREP to this function
1743 interactively by supplying any prefix argument.
1745 If the register contains a rectangle, then the rectangle is
1746 inserted with its upper left corner at point. This means that
1747 text is inserted in the current line and underneath it on
1750 If the register contains something other than saved text (a
1751 string) or a rectangle (a list), currently useless things happen.
1752 This may be changed in the future.
1755 File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
1757 43.21 Transposition of Text
1758 ===========================
1760 This subroutine is used by the transposition commands.
1762 -- Function: transpose-regions start1 end1 start2 end2 &optional
1764 This function exchanges two nonoverlapping portions of the buffer.
1765 Arguments START1 and END1 specify the bounds of one portion and
1766 arguments START2 and END2 specify the bounds of the other portion.
1768 Normally, `transpose-regions' relocates markers with the transposed
1769 text; a marker previously positioned within one of the two
1770 transposed portions moves along with that portion, thus remaining
1771 between the same two characters in their new position. However,
1772 if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
1773 this--it leaves all markers unrelocated.
1776 File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
1781 These hook variables let you arrange to take notice of all changes in
1782 all buffers (or in a particular buffer, if you make them buffer-local).
1784 The functions you use in these hooks should save and restore the
1785 match data if they do anything that uses regular expressions;
1786 otherwise, they will interfere in bizarre ways with the editing
1787 operations that call them.
1789 Buffer changes made while executing the following hooks don't
1790 themselves cause any change hooks to be invoked.
1792 -- Variable: before-change-functions
1793 This variable holds a list of a functions to call before any buffer
1794 modification. Each function gets two arguments, the beginning and
1795 end of the region that is about to change, represented as
1796 integers. The buffer that is about to change is always the
1799 -- Variable: after-change-functions
1800 This variable holds a list of a functions to call after any buffer
1801 modification. Each function receives three arguments: the
1802 beginning and end of the region just changed, and the length of
1803 the text that existed before the change. (To get the current
1804 length, subtract the region beginning from the region end.) All
1805 three arguments are integers. The buffer that's about to change
1806 is always the current buffer.
1808 -- Variable: before-change-function
1809 This obsolete variable holds one function to call before any buffer
1810 modification (or `nil' for no function). It is called just like
1811 the functions in `before-change-functions'.
1813 -- Variable: after-change-function
1814 This obsolete variable holds one function to call after any buffer
1815 modification (or `nil' for no function). It is called just like
1816 the functions in `after-change-functions'.
1818 -- Variable: first-change-hook
1819 This variable is a normal hook that is run whenever a buffer is
1820 changed that was previously in the unmodified state.
1823 File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text
1825 43.23 Textual transformations--MD5 and base64 support
1826 =====================================================
1828 Some textual operations inherently require examining each character in
1829 turn, and performing arithmetic operations on them. Such operations
1830 can, of course, be implemented in Emacs Lisp, but tend to be very slow
1831 for large portions of text or data. This is why some of them are
1832 implemented in C, with an appropriate interface for Lisp programmers.
1833 Examples of algorithms thus provided are MD5 and base64 support.
1835 MD5 is an algorithm for calculating message digests, as described in
1836 rfc1321. Given a message of arbitrary length, MD5 produces a 128-bit
1837 "fingerprint" ("message digest") corresponding to that message. It is
1838 considered computationally infeasible to produce two messages having
1839 the same MD5 digest, or to produce a message having a prespecified
1840 target digest. MD5 is used heavily by various authentication schemes.
1842 Emacs Lisp interface to MD5 consists of a single function `md5':
1844 -- Function: md5 object &optional start end coding noerror
1845 This function returns the MD5 message digest of OBJECT, a buffer
1848 Optional arguments START and END denote positions for computing
1849 the digest of a portion of OBJECT.
1851 The optional CODING argument specifies the coding system the text
1852 is to be represented in while computing the digest. If
1853 unspecified, it defaults to the current format of the data, or is
1856 If NOERROR is non-`nil', silently assume binary coding if the
1857 guesswork fails. Normally, an error is signaled in such case.
1859 CODING and NOERROR arguments are meaningful only in XEmacsen with
1860 file-coding or Mule support. Otherwise, they are ignored. Some
1863 ;; Calculate the digest of the entire buffer
1864 (md5 (current-buffer))
1865 => "8842b04362899b1cda8d2d126dc11712"
1867 ;; Calculate the digest of the current line
1868 (md5 (current-buffer) (point-at-bol) (point-at-eol))
1869 => "60614d21e9dee27dfdb01fa4e30d6d00"
1871 ;; Calculate the digest of your name and email address
1872 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
1873 => "0a2188c40fd38922d941fe6032fce516"
1875 Base64 is a portable encoding for arbitrary sequences of octets, in a
1876 form that need not be readable by humans. It uses a 65-character subset
1877 of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
1878 binary bodies, and to encode binary characters in message headers.
1880 The Lisp interface to base64 consists of four functions:
1882 -- Command: base64-encode-region start end &optional no-line-break
1883 This function encodes the region between START and END of the
1884 current buffer to base64 format. This means that the original
1885 region is deleted, and replaced with its base64 equivalent.
1887 Normally, encoded base64 output is multi-line, with 76-character
1888 lines. If NO-LINE-BREAK is non-`nil', newlines will not be
1889 inserted, resulting in single-line output.
1891 Mule note: you should make sure that you convert the multibyte
1892 characters (those that do not fit into 0-255 range) to something
1893 else, because they cannot be meaningfully converted to base64. If
1894 the `base64-encode-region' encounters such characters, it will
1897 `base64-encode-region' returns the length of the encoded text.
1899 ;; Encode the whole buffer in base64
1900 (base64-encode-region (point-min) (point-max))
1902 The function can also be used interactively, in which case it
1903 works on the currently active region.
1905 -- Function: base64-encode-string string &optional no-line-break
1906 This function encodes STRING to base64, and returns the encoded
1909 Normally, encoded base64 output is multi-line, with 76-character
1910 lines. If NO-LINE-BREAK is non-`nil', newlines will not be
1911 inserted, resulting in single-line output.
1913 For Mule, the same considerations apply as for
1914 `base64-encode-region'.
1916 (base64-encode-string "fubar")
1919 -- Command: base64-decode-region start end
1920 This function decodes the region between START and END of the
1921 current buffer. The region should be in base64 encoding.
1923 If the region was decoded correctly, `base64-decode-region' returns
1924 the length of the decoded region. If the decoding failed, `nil' is
1927 ;; Decode a base64 buffer, and replace it with the decoded version
1928 (base64-decode-region (point-min) (point-max))
1930 -- Function: base64-decode-string string
1931 This function decodes STRING to base64, and returns the decoded
1932 string. STRING should be valid base64-encoded text.
1934 If encoding was not possible, `nil' is returned.
1936 (base64-decode-string "ZnViYXI=")
1939 (base64-decode-string "totally bogus")
1943 File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top
1945 44 Searching and Matching
1946 *************************
1948 XEmacs provides two ways to search through a buffer for specified text:
1949 exact string searches and regular expression searches. After a regular
1950 expression search, you can examine the "match data" to determine which
1951 text matched the whole regular expression or various portions of it.
1955 * String Search:: Search for an exact match.
1956 * Regular Expressions:: Describing classes of strings.
1957 * Regexp Search:: Searching for a match for a regexp.
1958 * POSIX Regexps:: Searching POSIX-style for the longest match.
1959 * Search and Replace:: Internals of `query-replace'.
1960 * Match Data:: Finding out which part of the text matched
1961 various parts of a regexp, after regexp search.
1962 * Searching and Case:: Case-independent or case-significant searching.
1963 * Standard Regexps:: Useful regexps for finding sentences, pages,...
1965 The `skip-chars...' functions also perform a kind of searching.
1966 *Note Skipping Characters::.
1969 File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching
1971 44.1 Searching for Strings
1972 ==========================
1974 These are the primitive functions for searching through the text in a
1975 buffer. They are meant for use in programs, but you may call them
1976 interactively. If you do so, they prompt for the search string; LIMIT
1977 and NOERROR are set to `nil', and COUNT is set to 1.
1979 -- Command: search-forward string &optional limit noerror count buffer
1980 This function searches forward from point for an exact match for
1981 STRING. If successful, it sets point to the end of the occurrence
1982 found, and returns the new value of point. If no match is found,
1983 the value and side effects depend on NOERROR (see below).
1985 In the following example, point is initially at the beginning of
1986 the line. Then `(search-forward "fox")' moves point after the last
1989 ---------- Buffer: foo ----------
1990 -!-The quick brown fox jumped over the lazy dog.
1991 ---------- Buffer: foo ----------
1993 (search-forward "fox")
1996 ---------- Buffer: foo ----------
1997 The quick brown fox-!- jumped over the lazy dog.
1998 ---------- Buffer: foo ----------
2000 The argument LIMIT specifies the upper bound to the search. (It
2001 must be a position in the current buffer.) No match extending
2002 after that position is accepted. If LIMIT is omitted or `nil', it
2003 defaults to the end of the accessible portion of the buffer.
2005 What happens when the search fails depends on the value of
2006 NOERROR. If NOERROR is `nil', a `search-failed' error is
2007 signaled. If NOERROR is `t', `search-forward' returns `nil' and
2008 does nothing. If NOERROR is neither `nil' nor `t', then
2009 `search-forward' moves point to the upper bound and returns `nil'.
2010 (It would be more consistent now to return the new position of
2011 point in that case, but some programs may depend on a value of
2014 If COUNT is supplied (it must be an integer), then the search is
2015 repeated that many times (each time starting at the end of the
2016 previous time's match). If COUNT is negative, the search
2017 direction is backward. If the successive searches succeed, the
2018 function succeeds, moving point and returning its new value.
2019 Otherwise the search fails.
2021 BUFFER is the buffer to search in, and defaults to the current
2024 -- Command: search-backward string &optional limit noerror count buffer
2025 This function searches backward from point for STRING. It is just
2026 like `search-forward' except that it searches backwards and leaves
2027 point at the beginning of the match.
2029 -- Command: word-search-forward string &optional limit noerror count
2031 This function searches forward from point for a "word" match for
2032 STRING. If it finds a match, it sets point to the end of the
2033 match found, and returns the new value of point.
2035 Word matching regards STRING as a sequence of words, disregarding
2036 punctuation that separates them. It searches the buffer for the
2037 same sequence of words. Each word must be distinct in the buffer
2038 (searching for the word `ball' does not match the word `balls'),
2039 but the details of punctuation and spacing are ignored (searching
2040 for `ball boy' does match `ball. Boy!').
2042 In this example, point is initially at the beginning of the
2043 buffer; the search leaves it between the `y' and the `!'.
2045 ---------- Buffer: foo ----------
2046 -!-He said "Please! Find
2048 ---------- Buffer: foo ----------
2050 (word-search-forward "Please find the ball, boy.")
2053 ---------- Buffer: foo ----------
2054 He said "Please! Find
2056 ---------- Buffer: foo ----------
2058 If LIMIT is non-`nil' (it must be a position in the current
2059 buffer), then it is the upper bound to the search. The match
2060 found must not extend after that position.
2062 If NOERROR is `nil', then `word-search-forward' signals an error
2063 if the search fails. If NOERROR is `t', then it returns `nil'
2064 instead of signaling an error. If NOERROR is neither `nil' nor
2065 `t', it moves point to LIMIT (or the end of the buffer) and
2068 If COUNT is non-`nil', then the search is repeated that many
2069 times. Point is positioned at the end of the last match.
2071 BUFFER is the buffer to search in, and defaults to the current
2074 -- Command: word-search-backward string &optional limit noerror count
2076 This function searches backward from point for a word match to
2077 STRING. This function is just like `word-search-forward' except
2078 that it searches backward and normally leaves point at the
2079 beginning of the match.
2082 File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching
2084 44.2 Regular Expressions
2085 ========================
2087 A "regular expression" ("regexp", for short) is a pattern that denotes
2088 a (possibly infinite) set of strings. Searching for matches for a
2089 regexp is a very powerful operation. This section explains how to write
2090 regexps; the following section says how to search for them.
2092 To gain a thorough understanding of regular expressions and how to
2093 use them to best advantage, we recommend that you study `Mastering
2094 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
2095 1997'. (It's known as the "Hip Owls" book, because of the picture on its
2096 cover.) You might also read the manuals to *Note (gawk)Top::, *Note
2097 (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
2098 (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
2099 regular expressions.
2101 The XEmacs regular expression syntax most closely resembles that of
2102 `ed', or `grep', the GNU versions of which all utilize the GNU `regex'
2103 library. XEmacs' version of `regex' has recently been extended with
2104 some Perl-like capabilities, described in the next section.
2108 * Syntax of Regexps:: Rules for writing regular expressions.
2109 * Regexp Example:: Illustrates regular expression syntax.
2112 File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions
2114 44.2.1 Syntax of Regular Expressions
2115 ------------------------------------
2117 Regular expressions have a syntax in which a few characters are special
2118 constructs and the rest are "ordinary". An ordinary character is a
2119 simple regular expression that matches that character and nothing else.
2120 The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
2121 `\'; no new special characters will be defined in the future. Any
2122 other character appearing in a regular expression is ordinary, unless a
2125 For example, `f' is not a special character, so it is ordinary, and
2126 therefore `f' is a regular expression that matches the string `f' and
2127 no other string. (It does _not_ match the string `ff'.) Likewise, `o'
2128 is a regular expression that matches only `o'.
2130 Any two regular expressions A and B can be concatenated. The result
2131 is a regular expression that matches a string if A matches some amount
2132 of the beginning of that string and B matches the rest of the string.
2134 As a simple example, we can concatenate the regular expressions `f'
2135 and `o' to get the regular expression `fo', which matches only the
2136 string `fo'. Still trivial. To do something more powerful, you need
2137 to use one of the special characters. Here is a list of them:
2140 is a special character that matches any single character except a
2141 newline. Using concatenation, we can make regular expressions
2142 like `a.b', which matches any three-character string that begins
2143 with `a' and ends with `b'.
2146 is not a construct by itself; it is a quantifying suffix operator
2147 that means to repeat the preceding regular expression as many
2148 times as possible. In `fo*', the `*' applies to the `o', so `fo*'
2149 matches one `f' followed by any number of `o's. The case of zero
2150 `o's is allowed: `fo*' does match `f'.
2152 `*' always applies to the _smallest_ possible preceding
2153 expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
2155 The matcher processes a `*' construct by matching, immediately, as
2156 many repetitions as can be found; it is "greedy". Then it
2157 continues with the rest of the pattern. If that fails,
2158 backtracking occurs, discarding some of the matches of the
2159 `*'-modified construct in case that makes it possible to match the
2160 rest of the pattern. For example, in matching `ca*ar' against the
2161 string `caaar', the `a*' first tries to match all three `a's; but
2162 the rest of the pattern is `ar' and there is only `r' left to
2163 match, so this try fails. The next alternative is for `a*' to
2164 match only two `a's. With this choice, the rest of the regexp
2165 matches successfully.
2167 Nested repetition operators can be extremely slow if they specify
2168 backtracking loops. For example, it could take hours for the
2169 regular expression `\(x+y*\)*a' to match the sequence
2170 `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
2171 Emacs must try each imaginable way of grouping the 35 `x''s before
2172 concluding that none of them can work. To make sure your regular
2173 expressions run fast, check nested repetitions carefully.
2176 is a quantifying suffix operator similar to `*' except that the
2177 preceding expression must match at least once. It is also
2178 "greedy". So, for example, `ca+r' matches the strings `car' and
2179 `caaaar' but not the string `cr', whereas `ca*r' matches all three
2183 is a quantifying suffix operator similar to `*', except that the
2184 preceding expression can match either once or not at all. For
2185 example, `ca?r' matches `car' or `cr', but does not match anything
2189 works just like `*', except that rather than matching the longest
2190 match, it matches the shortest match. `*?' is known as a
2191 "non-greedy" quantifier, a regexp construct borrowed from Perl.
2193 This construct is very useful for when you want to match the text
2194 inside a pair of delimiters. For instance, `/\*.*?\*/' will match
2195 C comments in a string. This could not easily be achieved without
2196 the use of a non-greedy quantifier.
2198 This construct has not been available prior to XEmacs 20.4. It is
2199 not available in FSF Emacs.
2202 is the non-greedy version of `+'.
2205 is the non-greedy version of `?'.
2208 serves as an interval quantifier, analogous to `*' or `+', but
2209 specifies that the expression must match at least N times, but no
2210 more than M times. This syntax is supported by most Unix regexp
2211 utilities, and has been introduced to XEmacs for the version 20.3.
2213 Unfortunately, the non-greedy version of this quantifier does not
2214 exist currently, although it does in Perl.
2217 `[' begins a "character set", which is terminated by a `]'. In
2218 the simplest case, the characters between the two brackets form
2219 the set. Thus, `[ad]' matches either one `a' or one `d', and
2220 `[ad]*' matches any string composed of just `a's and `d's
2221 (including the empty string), from which it follows that `c[ad]*r'
2222 matches `cr', `car', `cdr', `caddaar', etc.
2224 The usual regular expression special characters are not special
2225 inside a character set. A completely different set of special
2226 characters exists inside character sets: `]', `-' and `^'.
2228 `-' is used for ranges of characters. To write a range, write two
2229 characters with a `-' between them. Thus, `[a-z]' matches any
2230 lower case letter. Ranges may be intermixed freely with individual
2231 characters, as in `[a-z$%.]', which matches any lower case letter
2232 or `$', `%', or a period.
2234 To include a `]' in a character set, make it the first character.
2235 For example, `[]a]' matches `]' or `a'. To include a `-', write
2236 `-' as the first character in the set, or put it immediately after
2237 a range. (You can replace one individual character C with the
2238 range `C-C' to make a place to put the `-'.) There is no way to
2239 write a set containing just `-' and `]'.
2241 To include `^' in a set, put it anywhere but at the beginning of
2245 `[^' begins a "complement character set", which matches any
2246 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
2247 all characters _except_ letters and digits.
2249 `^' is not special in a character set unless it is the first
2250 character. The character following the `^' is treated as if it
2251 were first (thus, `-' and `]' are not special there).
2253 Note that a complement character set can match a newline, unless
2254 newline is mentioned as one of the characters not to match.
2257 is a special character that matches the empty string, but only at
2258 the beginning of a line in the text being matched. Otherwise it
2259 fails to match anything. Thus, `^foo' matches a `foo' that occurs
2260 at the beginning of a line.
2262 When matching a string instead of a buffer, `^' matches at the
2263 beginning of the string or after a newline character `\n'.
2266 is similar to `^' but matches only at the end of a line. Thus,
2267 `x+$' matches a string of one `x' or more at the end of a line.
2269 When matching a string instead of a buffer, `$' matches at the end
2270 of the string or before a newline character `\n'.
2273 has two functions: it quotes the special characters (including
2274 `\'), and it introduces additional special constructs.
2276 Because `\' quotes special characters, `\$' is a regular
2277 expression that matches only `$', and `\[' is a regular expression
2278 that matches only `[', and so on.
2280 Note that `\' also has special meaning in the read syntax of Lisp
2281 strings (*note String Type::), and must be quoted with `\'. For
2282 example, the regular expression that matches the `\' character is
2283 `\\'. To write a Lisp string that contains the characters `\\',
2284 Lisp syntax requires you to quote each `\' with another `\'.
2285 Therefore, the read syntax for a regular expression matching `\'
2288 *Please note:* For historical compatibility, special characters are
2289 treated as ordinary ones if they are in contexts where their special
2290 meanings make no sense. For example, `*foo' treats `*' as ordinary
2291 since there is no preceding expression on which the `*' can act. It is
2292 poor practice to depend on this behavior; quote the special character
2293 anyway, regardless of where it appears.
2295 For the most part, `\' followed by any character matches only that
2296 character. However, there are several exceptions: characters that,
2297 when preceded by `\', are special constructs. Such characters are
2298 always ordinary when encountered on their own. Here is a table of `\'
2302 specifies an alternative. Two regular expressions A and B with
2303 `\|' in between form an expression that matches anything that
2304 either A or B matches.
2306 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
2308 `\|' applies to the largest possible surrounding expressions.
2309 Only a surrounding `\( ... \)' grouping can limit the grouping
2312 Full backtracking capability exists to handle multiple uses of
2316 is a grouping construct that serves three purposes:
2318 1. To enclose a set of `\|' alternatives for other operations.
2319 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
2321 2. To enclose an expression for a suffix operator such as `*' to
2322 act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
2323 (zero or more) number of `na' strings.
2325 3. To record a matched substring for future reference.
2327 This last application is not a consequence of the idea of a
2328 parenthetical grouping; it is a separate feature that happens to be
2329 assigned as a second meaning to the same `\( ... \)' construct
2330 because there is no conflict in practice between the two meanings.
2331 Here is an explanation of this feature:
2334 matches the same text that matched the DIGITth occurrence of a `\(
2337 In other words, after the end of a `\( ... \)' construct, the
2338 matcher remembers the beginning and end of the text matched by that
2339 construct. Then, later on in the regular expression, you can use
2340 `\' followed by DIGIT to match that same text, whatever it may
2343 The strings matching the first nine `\( ... \)' constructs
2344 appearing in a regular expression are assigned numbers 1 through 9
2345 in the order that the open parentheses appear in the regular
2346 expression. So you can use `\1' through `\9' to refer to the text
2347 matched by the corresponding `\( ... \)' constructs.
2349 For example, `\(.*\)\1' matches any newline-free string that is
2350 composed of two identical halves. The `\(.*\)' matches the first
2351 half, which may be anything, but the `\1' that follows must match
2352 the same exact text.
2355 is called a "shy" grouping operator, and it is used just like `\(
2356 ... \)', except that it does not cause the matched substring to be
2357 recorded for future reference.
2359 This is useful when you need a lot of grouping `\( ... \)'
2360 constructs, but only want to remember one or two - or if you have
2361 more than nine groupings and need to use backreferences to refer to
2362 the groupings at the end. It also allows construction of regular
2363 expressions from variable subexpressions that contain varying
2364 numbers of non-capturing subexpressions, without disturbing the
2365 group counts for the main expression. For example
2367 (let ((sre (if foo "\\(?:bar\\|baz\\)" "quux")))
2368 (re-search-forward (format "a\\(b+ %s c+\\) d" sre) nil t)
2371 It is very tedious to write this kind of code without shy groups,
2372 even if you know what all the alternative subexpressions will look
2375 Using `\(?: ... \)' rather than `\( ... \)' should give little
2376 performance gain, as the start of each group must be recorded for
2377 the purpose of back-tracking in any case, and no string copying is
2378 done until `match-string' is called.
2380 The shy grouping operator has been borrowed from Perl, and was not
2381 available prior to XEmacs 20.3, and has only been available in GNU
2382 Emacs since version 21.
2385 matches any word-constituent character. The editor syntax table
2386 determines which characters these are. *Note Syntax Tables::.
2389 matches any character that is not a word constituent.
2392 matches any character whose syntax is CODE. Here CODE is a
2393 character that represents a syntax code: thus, `w' for word
2394 constituent, `-' for whitespace, `(' for open parenthesis, etc.
2395 *Note Syntax Tables::, for a list of syntax codes and the
2396 characters that stand for them.
2399 matches any character whose syntax is not CODE.
2402 matches any character in CATEGORY. Only available under Mule,
2403 categories, and category tables, are further described in *Note
2404 Category Tables::. They are a mechanism for constructing classes
2405 of characters that can be local to a buffer, and that do not
2406 require complicated [] expressions every time they are referenced.
2409 matches any character outside CATEGORY. *Note Category Tables::,
2410 again, and note that this is only available under Mule.
2412 The following regular expression constructs match the empty
2413 string--that is, they don't use up any characters--but whether they
2414 match depends on the context.
2417 matches the empty string, but only at the beginning of the buffer
2418 or string being matched against.
2421 matches the empty string, but only at the end of the buffer or
2422 string being matched against.
2425 matches the empty string, but only at point. (This construct is
2426 not defined when matching against a string.)
2429 matches the empty string, but only at the beginning or end of a
2430 word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
2431 separate word. `\bballs?\b' matches `ball' or `balls' as a
2435 matches the empty string, but _not_ at the beginning or end of a
2439 matches the empty string, but only at the beginning of a word.
2442 matches the empty string, but only at the end of a word.
2444 Not every string is a valid regular expression. For example, a
2445 string with unbalanced square brackets is invalid (with a few
2446 exceptions, such as `[]]'), and so is a string that ends with a single
2447 `\'. If an invalid regular expression is passed to any of the search
2448 functions, an `invalid-regexp' error is signaled.
2450 -- Function: regexp-quote string
2451 This function returns a regular expression string that matches
2452 exactly STRING and nothing else. This allows you to request an
2453 exact string match when calling a function that wants a regular
2456 (regexp-quote "^The cat$")
2459 One use of `regexp-quote' is to combine an exact string match with
2460 context described as a regular expression. For example, this
2461 searches for the string that is the value of `string', surrounded
2465 (concat "\\s-" (regexp-quote string) "\\s-"))
2468 File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
2470 44.2.2 Complex Regexp Example
2471 -----------------------------
2473 Here is a complicated regexp, used by XEmacs to recognize the end of a
2474 sentence together with any whitespace that follows. It is the value of
2475 the variable `sentence-end'.
2477 First, we show the regexp as a string in Lisp syntax to distinguish
2478 spaces from tab characters. The string constant begins and ends with a
2479 double-quote. `\"' stands for a double-quote as part of the string,
2480 `\\' for a backslash as part of the string, `\t' for a tab and `\n' for
2483 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
2485 In contrast, if you evaluate the variable `sentence-end', you will
2490 "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
2493 In this output, tab and newline appear as themselves.
2495 This regular expression contains four parts in succession and can be
2496 deciphered as follows:
2499 The first part of the pattern is a character set that matches any
2500 one of three characters: period, question mark, and exclamation
2501 mark. The match must begin with one of these three characters.
2504 The second part of the pattern matches any closing braces and
2505 quotation marks, zero or more of them, that may follow the period,
2506 question mark or exclamation mark. The `\"' is Lisp syntax for a
2507 double-quote in a string. The `*' at the end indicates that the
2508 immediately preceding regular expression (a character set, in this
2509 case) may be repeated zero or more times.
2511 `\\($\\| $\\|\t\\| \\)'
2512 The third part of the pattern matches the whitespace that follows
2513 the end of a sentence: the end of a line, or a tab, or two spaces.
2514 The double backslashes mark the parentheses and vertical bars as
2515 regular expression syntax; the parentheses delimit a group and the
2516 vertical bars separate alternatives. The dollar sign is used to
2517 match the end of a line.
2520 Finally, the last part of the pattern matches any additional
2521 whitespace beyond the minimum needed to end a sentence.
2524 File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
2526 44.3 Regular Expression Searching
2527 =================================
2529 In XEmacs, you can search for the next match for a regexp either
2530 incrementally or not. Incremental search commands are described in the
2531 `The XEmacs Lisp Reference Manual'. *Note Regular Expression Search:
2532 (xemacs)Regexp Search. Here we describe only the search functions
2533 useful in programs. The principal one is `re-search-forward'.
2535 -- Command: re-search-forward regexp &optional limit noerror count
2537 This function searches forward in the current buffer for a string
2538 of text that is matched by the regular expression REGEXP. The
2539 function skips over any amount of text that is not matched by
2540 REGEXP, and leaves point at the end of the first match found. It
2541 returns the new value of point.
2543 If LIMIT is non-`nil' (it must be a position in the current
2544 buffer), then it is the upper bound to the search. No match
2545 extending after that position is accepted.
2547 What happens when the search fails depends on the value of
2548 NOERROR. If NOERROR is `nil', a `search-failed' error is
2549 signaled. If NOERROR is `t', `re-search-forward' does nothing and
2550 returns `nil'. If NOERROR is neither `nil' nor `t', then
2551 `re-search-forward' moves point to LIMIT (or the end of the
2552 buffer) and returns `nil'.
2554 If COUNT is supplied (it must be a positive number), then the
2555 search is repeated that many times (each time starting at the end
2556 of the previous time's match). If these successive searches
2557 succeed, the function succeeds, moving point and returning its new
2558 value. Otherwise the search fails.
2560 In the following example, point is initially before the `T'.
2561 Evaluating the search call moves point to the end of that line
2562 (between the `t' of `hat' and the newline).
2564 ---------- Buffer: foo ----------
2565 I read "-!-The cat in the hat
2567 ---------- Buffer: foo ----------
2569 (re-search-forward "[a-z]+" nil t 5)
2572 ---------- Buffer: foo ----------
2573 I read "The cat in the hat-!-
2575 ---------- Buffer: foo ----------
2577 -- Command: re-search-backward regexp &optional limit noerror count
2579 This function searches backward in the current buffer for a string
2580 of text that is matched by the regular expression REGEXP, leaving
2581 point at the beginning of the first text found.
2583 This function is analogous to `re-search-forward', but they are not
2584 simple mirror images. `re-search-forward' finds the match whose
2585 beginning is as close as possible to the starting point. If
2586 `re-search-backward' were a perfect mirror image, it would find the
2587 match whose end is as close as possible. However, in fact it
2588 finds the match whose beginning is as close as possible. The
2589 reason is that matching a regular expression at a given spot
2590 always works from beginning to end, and starts at a specified
2593 A true mirror-image of `re-search-forward' would require a special
2594 feature for matching regexps from end to beginning. It's not
2595 worth the trouble of implementing that.
2597 -- Function: string-match regexp string &optional start buffer
2598 This function returns the index of the start of the first match for
2599 the regular expression REGEXP in STRING, or `nil' if there is no
2600 match. If START is non-`nil', the search starts at that index in
2603 Optional arg BUFFER controls how case folding is done (according
2604 to the value of `case-fold-search' in BUFFER and BUFFER's case
2605 tables) and defaults to the current buffer.
2610 "quick" "The quick brown fox jumped quickly.")
2613 "quick" "The quick brown fox jumped quickly." 8)
2616 The index of the first character of the string is 0, the index of
2617 the second character is 1, and so on.
2619 After this function returns, the index of the first character
2620 beyond the match is available as `(match-end 0)'. *Note Match
2624 "quick" "The quick brown fox jumped quickly." 8)
2630 -- Function: split-string string &optional pattern
2631 This function splits STRING to substrings delimited by PATTERN,
2632 and returns a list of substrings. If PATTERN is omitted, it
2633 defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
2636 (split-string "foo bar")
2639 (split-string "something")
2642 (split-string "a:b:c" ":")
2645 (split-string ":a::b:c" ":")
2646 => ("" "a" "" "b" "c")
2648 -- Function: split-path path
2649 This function splits a search path into a list of strings. The
2650 path components are separated with the characters specified with
2651 `path-separator'. Under Unix, `path-separator' will normally be
2652 `:', while under Windows, it will be `;'.
2654 -- Function: looking-at regexp &optional buffer
2655 This function determines whether the text in the current buffer
2656 directly following point matches the regular expression REGEXP.
2657 "Directly following" means precisely that: the search is
2658 "anchored" and it can succeed only starting with the first
2659 character following point. The result is `t' if so, `nil'
2662 This function does not move point, but it updates the match data,
2663 which you can access using `match-beginning' and `match-end'.
2666 In this example, point is located directly before the `T'. If it
2667 were anywhere else, the result would be `nil'.
2669 ---------- Buffer: foo ----------
2670 I read "-!-The cat in the hat
2672 ---------- Buffer: foo ----------
2674 (looking-at "The cat in the hat$")
2678 File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
2680 44.4 POSIX Regular Expression Searching
2681 =======================================
2683 The usual regular expression functions do backtracking when necessary
2684 to handle the `\|' and repetition constructs, but they continue this
2685 only until they find _some_ match. Then they succeed and report the
2688 This section describes alternative search functions which perform the
2689 full backtracking specified by the POSIX standard for regular expression
2690 matching. They continue backtracking until they have tried all
2691 possibilities and found all matches, so they can report the longest
2692 match, as required by POSIX. This is much slower, so use these
2693 functions only when you really need the longest match.
2695 In Emacs versions prior to 19.29, these functions did not exist, and
2696 the functions described above implemented full POSIX backtracking.
2698 -- Command: posix-search-forward regexp &optional limit noerror count
2700 This is like `re-search-forward' except that it performs the full
2701 backtracking specified by the POSIX standard for regular expression
2704 -- Command: posix-search-backward regexp &optional limit noerror count
2706 This is like `re-search-backward' except that it performs the full
2707 backtracking specified by the POSIX standard for regular expression
2710 -- Function: posix-looking-at regexp &optional buffer
2711 This is like `looking-at' except that it performs the full
2712 backtracking specified by the POSIX standard for regular expression
2715 -- Function: posix-string-match regexp string &optional start buffer
2716 This is like `string-match' except that it performs the full
2717 backtracking specified by the POSIX standard for regular expression
2720 Optional arg BUFFER controls how case folding is done (according
2721 to the value of `case-fold-search' in BUFFER and BUFFER's case
2722 tables) and defaults to the current buffer.
2725 File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
2727 44.5 Search and Replace
2728 =======================
2730 -- Function: perform-replace from-string replacements query-flag
2731 regexp-flag delimited-flag &optional repeat-count map
2732 This function is the guts of `query-replace' and related commands.
2733 It searches for occurrences of FROM-STRING and replaces some or
2734 all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
2735 otherwise, it asks the user what to do about each one.
2737 If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
2738 regular expression; otherwise, it must match literally. If
2739 DELIMITED-FLAG is non-`nil', then only replacements surrounded by
2740 word boundaries are considered.
2742 The argument REPLACEMENTS specifies what to replace occurrences
2743 with. If it is a string, that string is used. It can also be a
2744 list of strings, to be used in cyclic order.
2746 If REPEAT-COUNT is non-`nil', it should be an integer. Then it
2747 specifies how many times to use each of the strings in the
2748 REPLACEMENTS list before advancing cyclicly to the next one.
2750 Normally, the keymap `query-replace-map' defines the possible user
2751 responses for queries. The argument MAP, if non-`nil', is a
2752 keymap to use instead of `query-replace-map'.
2754 -- Variable: query-replace-map
2755 This variable holds a special keymap that defines the valid user
2756 responses for `query-replace' and related functions, as well as
2757 `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways:
2759 * The "key bindings" are not commands, just symbols that are
2760 meaningful to the functions that use this map.
2762 * Prefix keys are not supported; each key binding must be for a
2763 single event key sequence. This is because the functions
2764 don't use read key sequence to get the input; instead, they
2765 read a single event and look it up "by hand."
2767 Here are the meaningful "bindings" for `query-replace-map'. Several
2768 of them are meaningful only for `query-replace' and friends.
2771 Do take the action being considered--in other words, "yes."
2774 Do not take action for this question--in other words, "no."
2777 Answer this question "no," and give up on the entire series of
2778 questions, assuming that the answers will be "no."
2781 Answer this question "yes," and give up on the entire series of
2782 questions, assuming that subsequent answers will be "no."
2785 Answer this question "yes," but show the results--don't advance yet
2786 to the next question.
2789 Answer this question and all subsequent questions in the series
2790 with "yes," without further user interaction.
2793 Move back to the previous place that a question was asked about.
2796 Enter a recursive edit to deal with this question--instead of any
2797 other action that would normally be taken.
2800 Delete the text being considered, then enter a recursive edit to
2804 Redisplay and center the window, then ask the same question again.
2807 Perform a quit right away. Only `y-or-n-p' and related functions
2811 Display some help, then ask again.
2814 File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
2819 XEmacs keeps track of the positions of the start and end of segments of
2820 text found during a regular expression search. This means, for example,
2821 that you can search for a complex pattern, such as a date in an Rmail
2822 message, and then extract parts of the match under control of the
2825 Because the match data normally describe the most recent search only,
2826 you must be careful not to do another search inadvertently between the
2827 search you wish to refer back to and the use of the match data. If you
2828 can't avoid another intervening search, you must save and restore the
2829 match data around it, to prevent it from being overwritten.
2833 * Simple Match Data:: Accessing single items of match data,
2834 such as where a particular subexpression started.
2835 * Replacing Match:: Replacing a substring that was matched.
2836 * Entire Match Data:: Accessing the entire match data at once, as a list.
2837 * Saving Match Data:: Saving and restoring the match data.
2840 File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
2842 44.6.1 Simple Match Data Access
2843 -------------------------------
2845 This section explains how to use the match data to find out what was
2846 matched by the last search or match operation.
2848 You can ask about the entire matching text, or about a particular
2849 parenthetical subexpression of a regular expression. The COUNT
2850 argument in the functions below specifies which. If COUNT is zero, you
2851 are asking about the entire match. If COUNT is positive, it specifies
2852 which subexpression you want.
2854 Recall that the subexpressions of a regular expression are those
2855 expressions grouped with escaped parentheses, `\(...\)'. The COUNTth
2856 subexpression is found by counting occurrences of `\(' from the
2857 beginning of the whole regular expression. The first subexpression is
2858 numbered 1, the second 2, and so on. Only regular expressions can have
2859 subexpressions--after a simple string search, the only information
2860 available is about the entire match.
2862 -- Function: match-string count &optional in-string
2863 This function returns, as a string, the text matched in the last
2864 search or match operation. It returns the entire text if COUNT is
2865 zero, or just the portion corresponding to the COUNTth
2866 parenthetical subexpression, if COUNT is positive. If COUNT is
2867 out of range, or if that subexpression didn't match anything, the
2870 If the last such operation was done against a string with
2871 `string-match', then you should pass the same string as the
2872 argument IN-STRING. Otherwise, after a buffer search or match,
2873 you should omit IN-STRING or pass `nil' for it; but you should
2874 make sure that the current buffer when you call `match-string' is
2875 the one in which you did the searching or matching.
2877 -- Function: match-beginning count
2878 This function returns the position of the start of text matched by
2879 the last regular expression searched for, or a subexpression of it.
2881 If COUNT is zero, then the value is the position of the start of
2882 the entire match. Otherwise, COUNT specifies a subexpression in
2883 the regular expression, and the value of the function is the
2884 starting position of the match for that subexpression.
2886 The value is `nil' for a subexpression inside a `\|' alternative
2887 that wasn't used in the match.
2889 -- Function: match-end count
2890 This function is like `match-beginning' except that it returns the
2891 position of the end of the match, rather than the position of the
2894 Here is an example of using the match data, with a comment showing
2895 the positions within the text:
2897 (string-match "\\(qu\\)\\(ick\\)"
2898 "The quick fox jumped quickly.")
2902 (match-string 0 "The quick fox jumped quickly.")
2904 (match-string 1 "The quick fox jumped quickly.")
2906 (match-string 2 "The quick fox jumped quickly.")
2909 (match-beginning 1) ; The beginning of the match
2910 => 4 ; with `qu' is at index 4.
2912 (match-beginning 2) ; The beginning of the match
2913 => 6 ; with `ick' is at index 6.
2915 (match-end 1) ; The end of the match
2916 => 6 ; with `qu' is at index 6.
2918 (match-end 2) ; The end of the match
2919 => 9 ; with `ick' is at index 9.
2921 Here is another example. Point is initially located at the beginning
2922 of the line. Searching moves point to between the space and the word
2923 `in'. The beginning of the entire match is at the 9th character of the
2924 buffer (`T'), and the beginning of the match for the first
2925 subexpression is at the 13th character (`c').
2928 (re-search-forward "The \\(cat \\)")
2930 (match-beginning 1))
2933 ---------- Buffer: foo ----------
2934 I read "The cat -!-in the hat comes back" twice.
2937 ---------- Buffer: foo ----------
2939 (In this case, the index returned is a buffer position; the first
2940 character of the buffer counts as 1.)
2943 File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
2945 44.6.2 Replacing the Text That Matched
2946 --------------------------------------
2948 This function replaces the text matched by the last search with
2951 -- Function: replace-match replacement &optional fixedcase literal
2953 This function replaces the text in the buffer (or in STRING) that
2954 was matched by the last search. It replaces that text with
2957 If you did the last search in a buffer, you should specify `nil'
2958 for STRING. Then `replace-match' does the replacement by editing
2959 the buffer; it leaves point at the end of the replacement text,
2962 If you did the search in a string, pass the same string as STRING.
2963 Then `replace-match' does the replacement by constructing and
2964 returning a new string.
2966 If the fourth argument STRING is a string, fifth argument
2967 STRBUFFER specifies the buffer to be used for syntax-table and
2968 case-table lookup and defaults to the current buffer. When STRING
2969 is not a string, the buffer that the match occurred in has
2970 automatically been remembered and you do not need to specify it.
2972 If FIXEDCASE is non-`nil', then the case of the replacement text
2973 is not changed; otherwise, the replacement text is converted to a
2974 different case depending upon the capitalization of the text to be
2975 replaced. If the original text is all upper case, the replacement
2976 text is converted to upper case. If the first word of the
2977 original text is capitalized, then the first word of the
2978 replacement text is capitalized. If the original text contains
2979 just one word, and that word is a capital letter, `replace-match'
2980 considers this a capitalized first word rather than all upper case.
2982 If `case-replace' is `nil', then case conversion is not done,
2983 regardless of the value of FIXEDCASE. *Note Searching and Case::.
2985 If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
2986 it is, the only alterations being case changes as needed. If it
2987 is `nil' (the default), then the character `\' is treated
2988 specially. If a `\' appears in REPLACEMENT, then it must be part
2989 of one of the following sequences:
2992 `\&' stands for the entire text being replaced.
2995 `\N', where N is a digit, stands for the text that matched
2996 the Nth subexpression in the original regexp. Subexpressions
2997 are those expressions grouped inside `\(...\)'.
3000 `\\' stands for a single `\' in the replacement text.
3003 File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
3005 44.6.3 Accessing the Entire Match Data
3006 --------------------------------------
3008 The functions `match-data' and `set-match-data' read or write the
3009 entire match data, all at once.
3011 -- Function: match-data &optional integers reuse
3012 This function returns a newly constructed list containing all the
3013 information on what text the last search matched. Element zero is
3014 the position of the beginning of the match for the whole
3015 expression; element one is the position of the end of the match
3016 for the expression. The next two elements are the positions of
3017 the beginning and end of the match for the first subexpression,
3018 and so on. In general, element number 2N corresponds to
3019 `(match-beginning N)'; and element number 2N + 1 corresponds to
3022 All the elements are markers or `nil' if matching was done on a
3023 buffer, and all are integers or `nil' if matching was done on a
3024 string with `string-match'. However, if the optional first
3025 argument INTEGERS is non-`nil', always use integers (rather than
3026 markers) to represent buffer positions.
3028 If the optional second argument REUSE is a list, reuse it as part
3029 of the value. If REUSE is long enough to hold all the values, and
3030 if INTEGERS is non-`nil', no new lisp objects are created.
3032 As always, there must be no possibility of intervening searches
3033 between the call to a search function and the call to `match-data'
3034 that is intended to access the match data for that search.
3037 => (#<marker at 9 in foo>
3038 #<marker at 17 in foo>
3039 #<marker at 13 in foo>
3040 #<marker at 17 in foo>)
3042 -- Function: set-match-data match-list
3043 This function sets the match data from the elements of MATCH-LIST,
3044 which should be a list that was the value of a previous call to
3047 If MATCH-LIST refers to a buffer that doesn't exist, you don't get
3048 an error; that sets the match data in a meaningless but harmless
3051 `store-match-data' is an alias for `set-match-data'.
3054 File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
3056 44.6.4 Saving and Restoring the Match Data
3057 ------------------------------------------
3059 When you call a function that may do a search, you may need to save and
3060 restore the match data around that call, if you want to preserve the
3061 match data from an earlier search for later use. Here is an example
3062 that shows the problem that arises if you fail to save the match data:
3064 (re-search-forward "The \\(cat \\)")
3066 (foo) ; Perhaps `foo' does
3069 => 61 ; Unexpected result--not 48!
3071 You can save and restore the match data with `save-match-data':
3073 -- Special Form: save-match-data body...
3074 This special form executes BODY, saving and restoring the match
3077 You can use `set-match-data' together with `match-data' to imitate
3078 the effect of the special form `save-match-data'. This is useful for
3079 writing code that can run in Emacs 18. Here is how:
3081 (let ((data (match-data)))
3083 ... ; May change the original match data.
3084 (set-match-data data)))
3086 Emacs automatically saves and restores the match data when it runs
3087 process filter functions (*note Filter Functions::) and process
3088 sentinels (*note Sentinels::).
3091 File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
3093 44.7 Searching and Case
3094 =======================
3096 By default, searches in Emacs ignore the case of the text they are
3097 searching through; if you specify searching for `FOO', then `Foo' or
3098 `foo' is also considered a match. Regexps, and in particular character
3099 sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
3101 If you do not want this feature, set the variable `case-fold-search'
3102 to `nil'. Then all letters must match exactly, including case. This
3103 is a buffer-local variable; altering the variable affects only the
3104 current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you
3105 may change the value of `default-case-fold-search', which is the
3106 default value of `case-fold-search' for buffers that do not override it.
3108 Note that the user-level incremental search feature handles case
3109 distinctions differently. When given a lower case letter, it looks for
3110 a match of either case, but when given an upper case letter, it looks
3111 for an upper case letter only. But this has nothing to do with the
3112 searching functions Lisp functions use.
3114 -- User Option: case-replace
3115 This variable determines whether the replacement functions should
3116 preserve case. If the variable is `nil', that means to use the
3117 replacement text verbatim. A non-`nil' value means to convert the
3118 case of the replacement text according to the text being replaced.
3120 The function `replace-match' is where this variable actually has
3121 its effect. *Note Replacing Match::.
3123 -- User Option: case-fold-search
3124 This buffer-local variable determines whether searches should
3125 ignore case. If the variable is `nil' they do not ignore case;
3126 otherwise they do ignore case.
3128 -- Variable: default-case-fold-search
3129 The value of this variable is the default value for
3130 `case-fold-search' in buffers that do not override it. This is the
3131 same as `(default-value 'case-fold-search)'.
3134 File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching
3136 44.8 Standard Regular Expressions Used in Editing
3137 =================================================
3139 This section describes some variables that hold regular expressions
3140 used for certain purposes in editing:
3142 -- Variable: page-delimiter
3143 This is the regexp describing line-beginnings that separate pages.
3144 The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
3145 matches a line that starts with a formfeed character.
3147 The following two regular expressions should _not_ assume the match
3148 always starts at the beginning of a line; they should not use `^' to
3149 anchor the match. Most often, the paragraph commands do check for a
3150 match only at the beginning of a line, which means that `^' would be
3151 superfluous. When there is a nonzero left margin, they accept matches
3152 that start after the left margin. In that case, a `^' would be
3153 incorrect. However, a `^' is harmless in modes where a left margin is
3156 -- Variable: paragraph-separate
3157 This is the regular expression for recognizing the beginning of a
3158 line that separates paragraphs. (If you change this, you may have
3159 to change `paragraph-start' also.) The default value is
3160 `"[ \t\f]*$"', which matches a line that consists entirely of
3161 spaces, tabs, and form feeds (after its left margin).
3163 -- Variable: paragraph-start
3164 This is the regular expression for recognizing the beginning of a
3165 line that starts _or_ separates paragraphs. The default value is
3166 `"[ \t\n\f]"', which matches a line starting with a space, tab,
3167 newline, or form feed (after its left margin).
3169 -- Variable: sentence-end
3170 This is the regular expression describing the end of a sentence.
3171 (All paragraph boundaries also end sentences, regardless.) The
3174 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
3176 This means a period, question mark or exclamation mark, followed
3177 optionally by a closing parenthetical character, followed by tabs,
3178 spaces or new lines.
3180 For a detailed explanation of this regular expression, see *Note
3184 File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
3189 A "syntax table" specifies the syntactic textual function of each
3190 character. This information is used by the parsing commands, the
3191 complex movement commands, and others to determine where words, symbols,
3192 and other syntactic constructs begin and end. The current syntax table
3193 controls the meaning of the word motion functions (*note Word Motion::)
3194 and the list motion functions (*note List Motion::) as well as the
3195 functions in this chapter.
3199 * Basics: Syntax Basics. Basic concepts of syntax tables.
3200 * Desc: Syntax Descriptors. How characters are classified.
3201 * Syntax Table Functions:: How to create, examine and alter syntax tables.
3202 * Motion and Syntax:: Moving over characters with certain syntaxes.
3203 * Parsing Expressions:: Parsing balanced expressions
3204 using the syntax table.
3205 * Standard Syntax Tables:: Syntax tables used by various major modes.
3206 * Syntax Table Internals:: How syntax table information is stored.
3209 File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables
3211 45.1 Syntax Table Concepts
3212 ==========================
3214 A "syntax table" provides Emacs with the information that determines
3215 the syntactic use of each character in a buffer. This information is
3216 used by the parsing commands, the complex movement commands, and others
3217 to determine where words, symbols, and other syntactic constructs begin
3218 and end. The current syntax table controls the meaning of the word
3219 motion functions (*note Word Motion::) and the list motion functions
3220 (*note List Motion::) as well as the functions in this chapter.
3222 Under XEmacs 20 and later, a syntax table is a particular subtype of the
3223 primitive char table type (*note Char Tables::), and each element of the
3224 char table is an integer that encodes the syntax of the character in
3225 question, or a cons of such an integer and a matching character (for
3226 characters with parenthesis syntax).
3228 Under XEmacs 19, a syntax table is a vector of 256 elements; it
3229 contains one entry for each of the 256 possible characters in an 8-bit
3230 byte. Each element is an integer that encodes the syntax of the
3231 character in question. (The matching character, if any, is embedded in
3232 the bits of this integer.)
3234 Syntax tables are used only for moving across text, not for the Emacs
3235 Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading
3236 Lisp expressions, and these rules cannot be changed.
3238 Each buffer has its own major mode, and each major mode has its own
3239 idea of the syntactic class of various characters. For example, in Lisp
3240 mode, the character `;' begins a comment, but in C mode, it terminates
3241 a statement. To support these variations, XEmacs makes the choice of
3242 syntax table local to each buffer. Typically, each major mode has its
3243 own syntax table and installs that table in each buffer that uses that
3244 mode. Changing this table alters the syntax in all those buffers as
3245 well as in any buffers subsequently put in that mode. Occasionally
3246 several similar modes share one syntax table. *Note Example Major
3247 Modes::, for an example of how to set up a syntax table.
3249 A syntax table can inherit the data for some characters from the
3250 standard syntax table, while specifying other characters itself. The
3251 "inherit" syntax class means "inherit this character's syntax from the
3252 standard syntax table." Most major modes' syntax tables inherit the
3253 syntax of character codes 0 through 31 and 128 through 255. This is
3254 useful with character sets such as ISO Latin-1 that have additional
3255 alphabetic characters in the range 128 to 255. Just changing the
3256 standard syntax for these characters affects all major modes.
3258 -- Function: syntax-table-p object
3259 This function returns `t' if OBJECT is a vector of length 256
3260 elements. This means that the vector may be a syntax table.
3261 However, according to this test, any vector of length 256 is
3262 considered to be a syntax table, no matter what its contents.
3265 File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables
3267 45.2 Syntax Descriptors
3268 =======================
3270 This section describes the syntax classes and flags that denote the
3271 syntax of a character, and how they are represented as a "syntax
3272 descriptor", which is a Lisp string that you pass to
3273 `modify-syntax-entry' to specify the desired syntax.
3275 XEmacs defines a number of "syntax classes". Each syntax table puts
3276 each character into one class. There is no necessary relationship
3277 between the class of a character in one syntax table and its class in
3280 Each class is designated by a mnemonic character, which serves as the
3281 name of the class when you need to specify a class. Usually the
3282 designator character is one that is frequently in that class; however,
3283 its meaning as a designator is unvarying and independent of what syntax
3284 that character currently has.
3286 A syntax descriptor is a Lisp string that specifies a syntax class, a
3287 matching character (used only for the parenthesis classes) and flags.
3288 The first character is the designator for a syntax class. The second
3289 character is the character to match; if it is unused, put a space there.
3290 Then come the characters for any desired flags. If no matching
3291 character or flags are needed, one character is sufficient.
3293 For example, the descriptor for the character `*' in C mode is
3294 `. 23' (i.e., punctuation, matching character slot unused, second
3295 character of a comment-starter, first character of an comment-ender),
3296 and the entry for `/' is `. 14' (i.e., punctuation, matching character
3297 slot unused, first character of a comment-starter, second character of
3302 * Syntax Class Table:: Table of syntax classes.
3303 * Syntax Flags:: Additional flags each character can have.
3306 File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors
3308 45.2.1 Table of Syntax Classes
3309 ------------------------------
3311 Here is a table of syntax classes, the characters that stand for them,
3312 their meanings, and examples of their use.
3314 -- Syntax class: whitespace character
3315 "Whitespace characters" (designated with `-') separate symbols and
3316 words from each other. Typically, whitespace characters have no
3317 other syntactic significance, and multiple whitespace characters
3318 are syntactically equivalent to a single one. Space, tab, newline
3319 and formfeed are almost always classified as whitespace. (The
3320 designator ` ' is accepted for backwards compatibility with older
3321 versions of XEmacs, but is deprecated. It is invalid in GNU
3324 -- Syntax class: word constituent
3325 "Word constituents" (designated with `w') are parts of normal
3326 English words and are typically used in variable and command names
3327 in programs. All upper- and lower-case letters, and the digits,
3328 are typically word constituents.
3330 -- Syntax class: symbol constituent
3331 "Symbol constituents" (designated with `_') are the extra
3332 characters that are used in variable and command names along with
3333 word constituents. For example, the symbol constituents class is
3334 used in Lisp mode to indicate that certain characters may be part
3335 of symbol names even though they are not part of English words.
3336 These characters are `$&*+-_<>'. In standard C, the only
3337 non-word-constituent character that is valid in symbols is
3340 -- Syntax class: punctuation character
3341 "Punctuation characters" (`.') are those characters that are used
3342 as punctuation in English, or are used in some way in a programming
3343 language to separate symbols from one another. Most programming
3344 language modes, including Emacs Lisp mode, have no characters in
3345 this class since the few characters that are not symbol or word
3346 constituents all have other uses.
3348 -- Syntax class: open parenthesis character
3349 -- Syntax class: close parenthesis character
3350 Open and close "parenthesis characters" are characters used in
3351 dissimilar pairs to surround sentences or expressions. Such a
3352 grouping is begun with an open parenthesis character and
3353 terminated with a close. Each open parenthesis character matches
3354 a particular close parenthesis character, and vice versa.
3355 Normally, XEmacs indicates momentarily the matching open
3356 parenthesis when you insert a close parenthesis. *Note Blinking::.
3358 The class of open parentheses is designated with `(', and that of
3359 close parentheses with `)'.
3361 In English text, and in C code, the parenthesis pairs are `()',
3362 `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and
3363 vectors (`()' and `[]') are classified as parenthesis characters.
3365 -- Syntax class: string quote
3366 "String quote characters" (designated with `"') are used in many
3367 languages, including Lisp and C, to delimit string constants. The
3368 same string quote character appears at the beginning and the end
3369 of a string. Such quoted strings do not nest.
3371 The parsing facilities of XEmacs consider a string as a single
3372 token. The usual syntactic meanings of the characters in the
3373 string are suppressed.
3375 The Lisp modes have two string quote characters: double-quote (`"')
3376 and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is
3377 used in Common Lisp. C also has two string quote characters:
3378 double-quote for strings, and single-quote (`'') for character
3381 English text has no string quote characters because English is not
3382 a programming language. Although quotation marks are used in
3383 English, we do not want them to turn off the usual syntactic
3384 properties of other characters in the quotation.
3386 -- Syntax class: escape
3387 An "escape character" (designated with `\') starts an escape
3388 sequence such as is used in C string and character constants. The
3389 character `\' belongs to this class in both C and Lisp. (In C, it
3390 is used thus only inside strings, but it turns out to cause no
3391 trouble to treat it this way throughout C code.)
3393 Characters in this class count as part of words if
3394 `words-include-escapes' is non-`nil'. *Note Word Motion::.
3396 -- Syntax class: character quote
3397 A "character quote character" (designated with `/') quotes the
3398 following character so that it loses its normal syntactic meaning.
3399 This differs from an escape character in that only the character
3400 immediately following is ever affected.
3402 Characters in this class count as part of words if
3403 `words-include-escapes' is non-`nil'. *Note Word Motion::.
3405 This class is used for backslash in TeX mode.
3407 -- Syntax class: paired delimiter
3408 "Paired delimiter characters" (designated with `$') are like
3409 string quote characters except that the syntactic properties of the
3410 characters between the delimiters are not suppressed. Only TeX
3411 mode uses a paired delimiter presently--the `$' that both enters
3412 and leaves math mode.
3414 -- Syntax class: expression prefix
3415 An "expression prefix operator" (designated with `'') is used for
3416 syntactic operators that are part of an expression if they appear
3417 next to one. These characters in Lisp include the apostrophe, `''
3418 (used for quoting), the comma, `,' (used in macros), and `#' (used
3419 in the read syntax for certain data types).
3421 -- Syntax class: comment starter
3422 -- Syntax class: comment ender
3423 The "comment starter" and "comment ender" characters are used in
3424 various languages to delimit comments. These classes are
3425 designated with `<' and `>', respectively.
3427 English text has no comment characters. In Lisp, the semicolon
3428 (`;') starts a comment and a newline or formfeed ends one.
3430 -- Syntax class: inherit
3431 This syntax class does not specify a syntax. It says to look in
3432 the standard syntax table to find the syntax of this character.
3433 The designator for this syntax code is `@'.
3436 File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors
3441 In addition to the classes, entries for characters in a syntax table
3442 can include flags. There are eleven possible flags, represented by the
3443 digits `1'-`8', and the lowercase letters `a', `b', and `p'.
3445 All the flags except `p' are used to describe comment delimiters.
3446 The digit flags indicate that a character can _also_ be part of a
3447 multi-character comment sequence, in addition to the syntactic
3448 properties associated with its character class. The flags must be
3449 independent of the class and each other for the sake of characters such
3450 as `*' in C mode, which is a punctuation character, _and_ the second
3451 character of a start-of-comment sequence (`/*'), _and_ the first
3452 character of an end-of-comment sequence (`*/').
3454 Emacs supports two comment styles simultaneously in any one syntax
3455 table. This is for the sake of C++. Each style of comment syntax has
3456 its own comment-start sequence and its own comment-end sequence. Each
3457 comment must stick to one style or the other; thus, if it starts with
3458 the comment-start sequence of style "b", it must also end with the
3459 comment-end sequence of style "b".
3461 As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary
3462 comment-start sequences and two arbitrary comment-end sequences. (Thus
3463 the need for 8 flags.) GNU Emacs restricts the comment-start sequences
3464 to start with the same character, XEmacs does not. This means that for
3465 two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses
3466 the digit flags `5'-`8'.
3468 A one character comment-end sequence applies to the "b" style if its
3469 first character has the `b' flag set; otherwise, it applies to the "a"
3470 style. The `a' flag is optional. These flags have no effect on
3471 non-comment characters; two-character styles are determined by the
3474 The flags for a character C are:
3476 * `1' means C is the start of a two-character comment-start sequence
3479 * `2' means C is the second character of such a sequence.
3481 * `3' means C is the start of a two-character comment-end sequence
3484 * `4' means C is the second character of such a sequence.
3486 * `5' means C is the start of a two-character comment-start sequence
3489 * `6' means C is the second character of such a sequence.
3491 * `7' means C is the start of a two-character comment-end sequence
3494 * `8' means C is the second character of such a sequence.
3496 * `a' means that C as a comment delimiter belongs to the default "a"
3497 comment style. (This flag is optional.)
3499 * `b' means that C as a comment delimiter belongs to the alternate
3502 * `p' identifies an additional "prefix character" for Lisp syntax.
3503 These characters are treated as whitespace when they appear between
3504 expressions. When they appear within an expression, they are
3505 handled according to their usual syntax codes.
3507 The function `backward-prefix-chars' moves back over these
3508 characters, as well as over characters whose primary syntax class
3509 is prefix (`''). *Note Motion and Syntax::.
3511 Lisp (as you would expect) has a simple comment syntax.
3519 Note that no flags are used. This defines two comment-delimiting
3523 This is a single-character comment-start sequence because the
3524 syntax class is `<'.
3527 This is a single character comment-end sequence because the syntax
3528 class is `>' and the `b' flag is not set.
3530 C++ (again, as you would expect) has a baroque, overrich, and
3531 excessively complex comment syntax.
3542 Note that the "b" style mixes one-character and two-character
3543 sequences. The table above defines four comment-delimiting sequences:
3546 This is a comment-start sequence for "a" style because the `1'
3547 flag is set on `/' and the `2' flag is set on `*'.
3550 This is a comment-start sequence for "b" style because both the `5'
3551 and the `6' flags are set on `/'.
3554 This is a comment-end sequence for "a" style because the `3' flag
3555 is set on `*' and the `4' flag is set on `/'.
3558 This is a comment-end sequence for "b" style, because the newline
3559 character has the `b' flag.
3562 File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables
3564 45.3 Syntax Table Functions
3565 ===========================
3567 In this section we describe functions for creating, accessing and
3568 altering syntax tables.
3570 -- Function: make-syntax-table &optional oldtable
3571 This function creates a new syntax table. Character codes 0
3572 through 31 and 128 through 255 are set up to inherit from the
3573 standard syntax table. The other character codes are set up by
3574 copying what the standard syntax table says about them.
3576 Most major mode syntax tables are created in this way.
3578 -- Function: copy-syntax-table &optional syntax-table
3579 This function constructs a copy of SYNTAX-TABLE and returns it.
3580 If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy
3581 of the current syntax table. Otherwise, an error is signaled if
3582 SYNTAX-TABLE is not a syntax table.
3584 -- Command: modify-syntax-entry char-range syntax-descriptor &optional
3586 This function sets the syntax entry for CHAR-RANGE according to
3587 SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a
3588 range of characters, as used with `put-char-table'. The syntax is
3589 changed only for SYNTAX-TABLE, which defaults to the current
3590 buffer's syntax table, and not in any other syntax table. The
3591 argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a
3592 string beginning with a class designator character, and optionally
3593 containing a matching character and flags as well. *Note Syntax
3596 This function always returns `nil'. The old syntax information in
3597 the table for CHAR-RANGE is discarded.
3599 An error is signaled if the first character of the syntax
3600 descriptor is not one of the twelve syntax class designator
3605 ;; Put the space character in class whitespace.
3606 (modify-syntax-entry ?\ " ")
3609 ;; Make `$' an open parenthesis character,
3610 ;; with `^' as its matching close.
3611 (modify-syntax-entry ?$ "(^")
3614 ;; Make `^' a close parenthesis character,
3615 ;; with `$' as its matching open.
3616 (modify-syntax-entry ?^ ")$")
3619 ;; Make `/' a punctuation character,
3620 ;; the first character of a start-comment sequence,
3621 ;; and the second character of an end-comment sequence.
3622 ;; This is used in C mode.
3623 (modify-syntax-entry ?/ ". 14")
3626 -- Function: char-syntax character &optional syntax-table
3627 This function returns the syntax class of CHARACTER, represented
3628 by its mnemonic designator character. This _only_ returns the
3629 class, not any matching parenthesis or flags.
3631 An error is signaled if CHARACTER is not a character.
3633 The characters that correspond to various syntax codes are listed
3634 in the documentation of `modify-syntax-entry'.
3636 Optional second argument SYNTAX-TABLE is the syntax table to be
3637 used, and defaults to the current buffer's syntax table.
3639 The following examples apply to C mode. The first example shows
3640 that the syntax class of space is whitespace (represented by a
3641 space). The second example shows that the syntax of `/' is
3642 punctuation. This does not show the fact that it is also part of
3643 comment-start and -end sequences. The third example shows that
3644 open parenthesis is in the class of open parentheses. This does
3645 not show the fact that it has a matching character, `)'.
3647 (char-to-string (char-syntax ?\ ))
3650 (char-to-string (char-syntax ?/))
3653 (char-to-string (char-syntax ?\())
3656 -- Function: set-syntax-table syntax-table &optional buffer
3657 This function makes SYNTAX-TABLE the syntax table for BUFFER, which
3658 defaults to the current buffer if omitted. It returns
3661 -- Function: syntax-table &optional buffer
3662 This function returns the syntax table for BUFFER, which defaults
3663 to the current buffer if omitted.
3666 File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables
3668 45.4 Motion and Syntax
3669 ======================
3671 This section describes functions for moving across characters in
3672 certain syntax classes. None of these functions exists in Emacs
3673 version 18 or earlier.
3675 -- Function: skip-syntax-forward syntaxes &optional limit buffer
3676 This function moves point forward across characters having syntax
3677 classes mentioned in SYNTAXES. It stops when it encounters the
3678 end of the buffer, or position LIMIT (if specified), or a
3679 character it is not supposed to skip. Optional argument BUFFER
3680 defaults to the current buffer if omitted.
3682 -- Function: skip-syntax-backward syntaxes &optional limit buffer
3683 This function moves point backward across characters whose syntax
3684 classes are mentioned in SYNTAXES. It stops when it encounters
3685 the beginning of the buffer, or position LIMIT (if specified), or a
3686 character it is not supposed to skip. Optional argument BUFFER
3687 defaults to the current buffer if omitted.
3690 -- Function: backward-prefix-chars &optional buffer
3691 This function moves point backward over any number of characters
3692 with expression prefix syntax. This includes both characters in
3693 the expression prefix syntax class, and characters with the `p'
3694 flag. Optional argument BUFFER defaults to the current buffer if
3698 File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
3700 45.5 Parsing Balanced Expressions
3701 =================================
3703 Here are several functions for parsing and scanning balanced
3704 expressions, also known as "sexps", in which parentheses match in
3705 pairs. The syntax table controls the interpretation of characters, so
3706 these functions can be used for Lisp expressions when in Lisp mode and
3707 for C expressions when in C mode. *Note List Motion::, for convenient
3708 higher-level functions for moving over balanced expressions.
3710 -- Function: parse-partial-sexp start limit &optional target-depth
3711 stop-before state stop-comment buffer
3712 This function parses a sexp in the current buffer starting at
3713 START, not scanning past LIMIT. It stops at position LIMIT or
3714 when certain criteria described below are met, and sets point to
3715 the location where parsing stops. It returns a value describing
3716 the status of the parse at the point where it stops.
3718 If STATE is `nil', START is assumed to be at the top level of
3719 parenthesis structure, such as the beginning of a function
3720 definition. Alternatively, you might wish to resume parsing in the
3721 middle of the structure. To do this, you must provide a STATE
3722 argument that describes the initial status of parsing.
3724 If the third argument TARGET-DEPTH is non-`nil', parsing stops if
3725 the depth in parentheses becomes equal to TARGET-DEPTH. The depth
3726 starts at 0, or at whatever is given in STATE.
3728 If the fourth argument STOP-BEFORE is non-`nil', parsing stops
3729 when it comes to any character that starts a sexp. If
3730 STOP-COMMENT is non-`nil', parsing stops when it comes to the
3733 The fifth argument STATE is an eight-element list of the same form
3734 as the value of this function, described below. The return value
3735 of one call may be used to initialize the state of the parse on
3736 another call to `parse-partial-sexp'.
3738 The result is a list of eight elements describing the final state
3741 0. The depth in parentheses, counting from 0.
3743 1. The character position of the start of the innermost
3744 parenthetical grouping containing the stopping point; `nil'
3747 2. The character position of the start of the last complete
3748 subexpression terminated; `nil' if none.
3750 3. Non-`nil' if inside a string. More precisely, this is the
3751 character that will terminate the string.
3753 4. `t' if inside a comment (of either style).
3755 5. `t' if point is just after a quote character.
3757 6. The minimum parenthesis depth encountered during this scan.
3759 7. `t' if inside a comment of style "b".
3761 Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
3763 This function is most often used to compute indentation for
3764 languages that have nested parentheses.
3766 -- Function: scan-lists from count depth &optional buffer noerror
3767 This function scans forward COUNT balanced parenthetical groupings
3768 from character number FROM. It returns the character position
3769 where the scan stops.
3771 If DEPTH is nonzero, parenthesis depth counting begins from that
3772 value. The only candidates for stopping are places where the
3773 depth in parentheses becomes zero; `scan-lists' counts COUNT such
3774 places and then stops. Thus, a positive value for DEPTH means go
3775 out DEPTH levels of parenthesis.
3777 Scanning ignores comments if `parse-sexp-ignore-comments' is
3780 If the scan reaches the beginning or end of the buffer (or its
3781 accessible portion), and the depth is not zero, an error is
3782 signaled. If the depth is zero but the count is not used up,
3785 If optional arg BUFFER is non-`nil', scanning occurs in that
3786 buffer instead of in the current buffer.
3788 If optional arg NOERROR is non-`nil', `scan-lists' will return
3789 `nil' instead of signalling an error.
3791 -- Function: scan-sexps from count &optional buffer noerror
3792 This function scans forward COUNT sexps from character position
3793 FROM. It returns the character position where the scan stops.
3795 Scanning ignores comments if `parse-sexp-ignore-comments' is
3798 If the scan reaches the beginning or end of (the accessible part
3799 of) the buffer in the middle of a parenthetical grouping, an error
3800 is signaled. If it reaches the beginning or end between groupings
3801 but before count is used up, `nil' is returned.
3803 If optional arg BUFFER is non-`nil', scanning occurs in that
3804 buffer instead of in the current buffer.
3806 If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
3807 instead of signalling an error.
3809 -- Variable: parse-sexp-ignore-comments
3810 If the value is non-`nil', then comments are treated as whitespace
3811 by the functions in this section and by `forward-sexp'.
3813 In older Emacs versions, this feature worked only when the comment
3814 terminator is something like `*/', and appears only to end a
3815 comment. In languages where newlines terminate comments, it was
3816 necessary make this variable `nil', since not every newline is the
3817 end of a comment. This limitation no longer exists.
3819 You can use `forward-comment' to move forward or backward over one
3820 comment or several comments.
3822 -- Function: forward-comment &optional count buffer
3823 This function moves point forward across COUNT comments (backward,
3824 if COUNT is negative). If it finds anything other than a comment
3825 or whitespace, it stops, leaving point at the place where it
3826 stopped. It also stops after satisfying COUNT. COUNT defaults to
3829 Optional argument BUFFER defaults to the current buffer.
3831 To move forward over all comments and whitespace following point, use
3832 `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
3833 to use, because the number of comments in the buffer cannot exceed that
3837 File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
3839 45.6 Some Standard Syntax Tables
3840 ================================
3842 Most of the major modes in XEmacs have their own syntax tables. Here
3843 are several of them:
3845 -- Function: standard-syntax-table
3846 This function returns the standard syntax table, which is the
3847 syntax table used in Fundamental mode.
3849 -- Variable: text-mode-syntax-table
3850 The value of this variable is the syntax table used in Text mode.
3852 -- Variable: c-mode-syntax-table
3853 The value of this variable is the syntax table for C-mode buffers.
3855 -- Variable: emacs-lisp-mode-syntax-table
3856 The value of this variable is the syntax table used in Emacs Lisp
3857 mode by editing commands. (It has no effect on the Lisp `read'
3861 File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
3863 45.7 Syntax Table Internals
3864 ===========================
3866 Each element of a syntax table is an integer that encodes the syntax of
3867 one character: the syntax class, possible matching character, and
3868 flags. Lisp programs don't usually work with the elements directly; the
3869 Lisp-level syntax table functions usually work with syntax descriptors
3870 (*note Syntax Descriptors::).
3872 The low 8 bits of each element of a syntax table indicate the syntax
3920 The next 8 bits are the matching opposite parenthesis (if the
3921 character has parenthesis syntax); otherwise, they are not meaningful.
3922 The next 6 bits are the flags.
3925 File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
3927 46 Abbrevs And Abbrev Expansion
3928 *******************************
3930 An abbreviation or "abbrev" is a string of characters that may be
3931 expanded to a longer string. The user can insert the abbrev string and
3932 find it replaced automatically with the expansion of the abbrev. This
3935 The set of abbrevs currently in effect is recorded in an "abbrev
3936 table". Each buffer has a local abbrev table, but normally all buffers
3937 in the same major mode share one abbrev table. There is also a global
3938 abbrev table. Normally both are used.
3940 An abbrev table is represented as an obarray containing a symbol for
3941 each abbreviation. The symbol's name is the abbreviation; its value is
3942 the expansion; its function definition is the hook function to do the
3943 expansion (*note Defining Abbrevs::); its property list cell contains
3944 the use count, the number of times the abbreviation has been expanded.
3945 Because these symbols are not interned in the usual obarray, they will
3946 never appear as the result of reading a Lisp expression; in fact,
3947 normally they are never used except by the code that handles abbrevs.
3948 Therefore, it is safe to use them in an extremely nonstandard way.
3949 *Note Creating Symbols::.
3951 For the user-level commands for abbrevs, see *Note Abbrev Mode:
3956 * Abbrev Mode:: Setting up XEmacs for abbreviation.
3957 * Tables: Abbrev Tables. Creating and working with abbrev tables.
3958 * Defining Abbrevs:: Specifying abbreviations and their expansions.
3959 * Files: Abbrev Files. Saving abbrevs in files.
3960 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
3961 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
3964 File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
3966 46.1 Setting Up Abbrev Mode
3967 ===========================
3969 Abbrev mode is a minor mode controlled by the value of the variable
3972 -- Variable: abbrev-mode
3973 A non-`nil' value of this variable turns on the automatic expansion
3974 of abbrevs when their abbreviations are inserted into a buffer.
3975 If the value is `nil', abbrevs may be defined, but they are not
3976 expanded automatically.
3978 This variable automatically becomes local when set in any fashion.
3980 -- Variable: default-abbrev-mode
3981 This is the value of `abbrev-mode' for buffers that do not
3982 override it. This is the same as `(default-value 'abbrev-mode)'.
3985 File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
3990 This section describes how to create and manipulate abbrev tables.
3992 -- Function: make-abbrev-table
3993 This function creates and returns a new, empty abbrev table--an
3994 obarray containing no symbols. It is a vector filled with zeros.
3996 -- Function: clear-abbrev-table table
3997 This function undefines all the abbrevs in abbrev table TABLE,
3998 leaving it empty. The function returns `nil'.
4000 -- Function: define-abbrev-table table-name definitions
4001 This function defines TABLE-NAME (a symbol) as an abbrev table
4002 name, i.e., as a variable whose value is an abbrev table. It
4003 defines abbrevs in the table according to DEFINITIONS, a list of
4004 elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The
4005 value is always `nil'.
4007 -- Variable: abbrev-table-name-list
4008 This is a list of symbols whose values are abbrev tables.
4009 `define-abbrev-table' adds the new abbrev table name to this list.
4011 -- Function: insert-abbrev-table-description name &optional human
4012 This function inserts before point a description of the abbrev
4013 table named NAME. The argument NAME is a symbol whose value is an
4014 abbrev table. The value is always `nil'.
4016 If HUMAN is non-`nil', the description is human-oriented.
4017 Otherwise the description is a Lisp expression--a call to
4018 `define-abbrev-table' that would define NAME exactly as it is
4022 File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
4024 46.3 Defining Abbrevs
4025 =====================
4027 These functions define an abbrev in a specified abbrev table.
4028 `define-abbrev' is the low-level basic function, while `add-abbrev' is
4029 used by commands that ask for information from the user.
4031 -- Function: add-abbrev table type arg
4032 This function adds an abbreviation to abbrev table TABLE based on
4033 information from the user. The argument TYPE is a string
4034 describing in English the kind of abbrev this will be (typically,
4035 `"global"' or `"mode-specific"'); this is used in prompting the
4036 user. The argument ARG is the number of words in the expansion.
4038 The return value is the symbol that internally represents the new
4039 abbrev, or `nil' if the user declines to confirm redefining an
4042 -- Function: define-abbrev table name &optional expansion hook count
4043 This function defines an abbrev in TABLE named NAME, to expand to
4044 EXPANSION, and call HOOK. The return value is an uninterned
4045 symbol that represents the abbrev inside XEmacs; its name is NAME.
4047 The argument NAME should be a string. The argument EXPANSION
4048 should be a string, or `nil' to undefine the abbrev.
4050 The argument HOOK is a function or `nil'. If HOOK is non-`nil',
4051 then it is called with no arguments after the abbrev is replaced
4052 with EXPANSION; point is located at the end of EXPANSION when HOOK
4055 The use count of the abbrev is initialized to zero.
4057 -- User Option: only-global-abbrevs
4058 If this variable is non-`nil', it means that the user plans to use
4059 global abbrevs only. This tells the commands that define
4060 mode-specific abbrevs to define global ones instead. This
4061 variable does not alter the behavior of the functions in this
4062 section; it is examined by their callers.
4065 File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
4067 46.4 Saving Abbrevs in Files
4068 ============================
4070 A file of saved abbrev definitions is actually a file of Lisp code.
4071 The abbrevs are saved in the form of a Lisp program to define the same
4072 abbrev tables with the same contents. Therefore, you can load the file
4073 with `load' (*note How Programs Do Loading::). However, the function
4074 `quietly-read-abbrev-file' is provided as a more convenient interface.
4076 User-level facilities such as `save-some-buffers' can save abbrevs
4077 in a file automatically, under the control of variables described here.
4079 -- User Option: abbrev-file-name
4080 This is the default file name for reading and saving abbrevs.
4082 -- Function: quietly-read-abbrev-file &optional filename
4083 This function reads abbrev definitions from a file named FILENAME,
4084 previously written with `write-abbrev-file'. If FILENAME is
4085 `nil', the file specified in `abbrev-file-name' is used.
4086 `save-abbrevs' is set to `t' so that changes will be saved.
4088 This function does not display any messages. It returns `nil'.
4090 -- User Option: save-abbrevs
4091 A non-`nil' value for `save-abbrev' means that XEmacs should save
4092 abbrevs when files are saved. `abbrev-file-name' specifies the
4093 file to save the abbrevs in.
4095 -- Variable: abbrevs-changed
4096 This variable is set non-`nil' by defining or altering any
4097 abbrevs. This serves as a flag for various XEmacs commands to
4098 offer to save your abbrevs.
4100 -- Command: write-abbrev-file filename
4101 Save all abbrev definitions, in all abbrev tables, in the file
4102 FILENAME, in the form of a Lisp program that when loaded will
4103 define the same abbrevs. This function returns `nil'.
4106 File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
4108 46.5 Looking Up and Expanding Abbreviations
4109 ===========================================
4111 Abbrevs are usually expanded by commands for interactive use, including
4112 `self-insert-command'. This section describes the subroutines used in
4113 writing such functions, as well as the variables they use for
4116 -- Function: abbrev-symbol abbrev &optional table
4117 This function returns the symbol representing the abbrev named
4118 ABBREV. The value returned is `nil' if that abbrev is not
4119 defined. The optional second argument TABLE is the abbrev table
4120 to look it up in. If TABLE is `nil', this function tries first
4121 the current buffer's local abbrev table, and second the global
4124 -- Function: abbrev-expansion abbrev &optional table
4125 This function returns the string that ABBREV would expand into (as
4126 defined by the abbrev tables used for the current buffer). The
4127 optional argument TABLE specifies the abbrev table to use, as in
4130 -- Command: expand-abbrev
4131 This command expands the abbrev before point, if any. If point
4132 does not follow an abbrev, this command does nothing. The command
4133 returns `t' if it did expansion, `nil' otherwise.
4135 -- Command: abbrev-prefix-mark &optional arg
4136 Mark current point as the beginning of an abbrev. The next call to
4137 `expand-abbrev' will use the text from here to point (where it is
4138 then) as the abbrev to expand, rather than using the previous word
4141 -- User Option: abbrev-all-caps
4142 When this is set non-`nil', an abbrev entered entirely in upper
4143 case is expanded using all upper case. Otherwise, an abbrev
4144 entered entirely in upper case is expanded by capitalizing each
4145 word of the expansion.
4147 -- Variable: abbrev-start-location
4148 This is the buffer position for `expand-abbrev' to use as the start
4149 of the next abbrev to be expanded. (`nil' means use the word
4150 before point instead.) `abbrev-start-location' is set to `nil'
4151 each time `expand-abbrev' is called. This variable is also set by
4152 `abbrev-prefix-mark'.
4154 -- Variable: abbrev-start-location-buffer
4155 The value of this variable is the buffer for which
4156 `abbrev-start-location' has been set. Trying to expand an abbrev
4157 in any other buffer clears `abbrev-start-location'. This variable
4158 is set by `abbrev-prefix-mark'.
4160 -- Variable: last-abbrev
4161 This is the `abbrev-symbol' of the last abbrev expanded. This
4162 information is left by `expand-abbrev' for the sake of the
4163 `unexpand-abbrev' command.
4165 -- Variable: last-abbrev-location
4166 This is the location of the last abbrev expanded. This contains
4167 information left by `expand-abbrev' for the sake of the
4168 `unexpand-abbrev' command.
4170 -- Variable: last-abbrev-text
4171 This is the exact expansion text of the last abbrev expanded,
4172 after case conversion (if any). Its value is `nil' if the abbrev
4173 has already been unexpanded. This contains information left by
4174 `expand-abbrev' for the sake of the `unexpand-abbrev' command.
4176 -- Variable: pre-abbrev-expand-hook
4177 This is a normal hook whose functions are executed, in sequence,
4178 just before any expansion of an abbrev. *Note Hooks::. Since it
4179 is a normal hook, the hook functions receive no arguments.
4180 However, they can find the abbrev to be expanded by looking in the
4181 buffer before point.
4183 The following sample code shows a simple use of
4184 `pre-abbrev-expand-hook'. If the user terminates an abbrev with a
4185 punctuation character, the hook function asks for confirmation. Thus,
4186 this hook allows the user to decide whether to expand the abbrev, and
4187 aborts expansion if it is not confirmed.
4189 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
4191 ;; This is the function invoked by `pre-abbrev-expand-hook'.
4193 ;; If the user terminated the abbrev with a space, the function does
4194 ;; nothing (that is, it returns so that the abbrev can expand). If the
4195 ;; user entered some other character, this function asks whether
4196 ;; expansion should continue.
4198 ;; If the user answers the prompt with `y', the function returns
4199 ;; `nil' (because of the `not' function), but that is
4200 ;; acceptable; the return value has no effect on expansion.
4202 (defun query-if-not-space ()
4203 (if (/= ?\ (preceding-char))
4204 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
4205 (error "Not expanding this abbrev"))))
4208 File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
4210 46.6 Standard Abbrev Tables
4211 ===========================
4213 Here we list the variables that hold the abbrev tables for the
4214 preloaded major modes of XEmacs.
4216 -- Variable: global-abbrev-table
4217 This is the abbrev table for mode-independent abbrevs. The abbrevs
4218 defined in it apply to all buffers. Each buffer may also have a
4219 local abbrev table, whose abbrev definitions take precedence over
4220 those in the global table.
4222 -- Variable: local-abbrev-table
4223 The value of this buffer-local variable is the (mode-specific)
4224 abbreviation table of the current buffer.
4226 -- Variable: fundamental-mode-abbrev-table
4227 This is the local abbrev table used in Fundamental mode; in other
4228 words, it is the local abbrev table in all buffers in Fundamental
4231 -- Variable: text-mode-abbrev-table
4232 This is the local abbrev table used in Text mode.
4234 -- Variable: c-mode-abbrev-table
4235 This is the local abbrev table used in C mode.
4237 -- Variable: lisp-mode-abbrev-table
4238 This is the local abbrev table used in Lisp mode and Emacs Lisp
4242 File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
4247 An "extent" is a region of text (a start position and an end position)
4248 that is displayed in a particular face and can have certain other
4249 properties such as being read-only. Extents can overlap each other.
4250 XEmacs efficiently handles buffers with large numbers of extents in
4253 -- Function: extentp object
4254 This returns `t' if OBJECT is an extent.
4258 * Intro to Extents:: Extents are regions over a buffer or string.
4259 * Creating and Modifying Extents::
4260 Basic extent functions.
4261 * Extent Endpoints:: Accessing and setting the bounds of an extent.
4262 * Finding Extents:: Determining which extents are in an object.
4263 * Mapping Over Extents:: More sophisticated functions for extent scanning.
4264 * Extent Properties:: Extents have built-in and user-definable properties.
4265 * Detached Extents:: Extents that are not in a buffer.
4266 * Extent Parents:: Inheriting properties from another extent.
4267 * Duplicable Extents:: Extents can be marked to be copied into strings.
4268 * Extents and Events:: Extents can interact with the keyboard and mouse.
4269 * Atomic Extents:: Treating a block of text as a single entity.
4272 File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents
4274 47.1 Introduction to Extents
4275 ============================
4277 An extent is a region of text within a buffer or string that has
4278 certain properties associated with it. The properties of an extent
4279 primarily affect the way the text contained in the extent is displayed.
4280 Extents can freely overlap each other in a buffer or string. Extents
4281 are invisible to functions that merely examine the text of a buffer or
4284 _Please note:_ An alternative way to add properties to a buffer or
4285 string is to use text properties. *Note Text Properties::.
4287 An extent is logically a Lisp object consisting of a start position,
4288 an end position, a buffer or string to which these positions refer, and
4289 a property list. As text is inserted into a buffer, the start and end
4290 positions of the extent are automatically adjusted as necessary to keep
4291 the extent referring to the same text in the buffer. If text is
4292 inserted at the boundary of an extent, the extent's `start-open' and
4293 `end-open' properties control whether the text is included as part of
4294 the extent. If the text bounded by an extent is deleted, the extent
4295 becomes "detached"; its start and end positions are no longer
4296 meaningful, but it maintains all its other properties and can later be
4297 reinserted into a buffer. (None of these considerations apply to
4298 strings, because text cannot be inserted into or deleted from a string.)
4300 Each extent has a face or list of faces associated with it, which
4301 controls the way in which the text bounded by the extent is displayed.
4302 If an extent's face is `nil' or its properties are partially undefined,
4303 the corresponding properties from the default face for the frame is
4304 used. If two or more extents overlap, or if a list of more than one
4305 face is specified for a particular extent, the corresponding faces are
4306 merged to determine the text's displayed properties. Every extent has
4307 a "priority" that determines which face takes precedence if the faces
4308 conflict. (If two extents have the same priority, the one that comes
4309 later in the display order takes precedence. *Note display order:
4310 Extent Endpoints.) Higher-numbered priority values correspond to a
4311 higher priority, and priority values can be negative. Every extent is
4312 created with a priority of 0, but this can be changed with
4313 `set-extent-priority'. Within a single extent with a list of faces,
4314 faces earlier in the list have a higher priority than faces later in
4317 Extents can be set to respond specially to key and mouse events
4318 within the extent. An extent's `keymap' property controls the effect of
4319 key and mouse strokes within the extent's text, and the `mouse-face'
4320 property controls whether the extent is highlighted when the mouse moves
4321 over it. *Note Extents and Events::.
4323 An extent can optionally have a "begin-glyph" or "end-glyph"
4324 associated with it. A begin-glyph or end-glyph is a pixmap or string
4325 that will be displayed either at the start or end of an extent or in the
4326 margin of the line that the start or end of the extent lies in,
4327 depending on the extent's layout policy. Begin-glyphs and end-glyphs
4328 are used to implement annotations, and you should use the annotation API
4329 functions in preference to the lower-level extent functions. For more
4330 information, *Note Annotations::.
4332 If an extent has its `detachable' property set, it will become
4333 "detached" (i.e. no longer in the buffer) when all its text is deleted.
4334 Otherwise, it will simply shrink down to zero-length and sit in the
4335 same place in the buffer. By default, the `detachable' property is set
4336 on newly-created extents. *Note Detached Extents::.
4338 If an extent has its `duplicable' property set, it will be
4339 remembered when a string is created from text bounded by the extent.
4340 When the string is re-inserted into a buffer, the extent will also be
4341 re-inserted. This mechanism is used in the kill, yank, and undo
4342 commands. *Note Duplicable Extents::.
4345 File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents
4347 47.2 Creating and Modifying Extents
4348 ===================================
4350 -- Function: make-extent from to &optional buffer-or-string
4351 This function makes an extent for the range [FROM, TO) in
4352 BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults
4353 to the current buffer. Insertions at point TO will be outside of
4354 the extent; insertions at FROM will be inside the extent, causing
4355 the extent to grow (*note Extent Endpoints::). This is the same
4356 way that markers behave. The extent is initially detached if both
4357 FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
4358 to `nil', meaning the extent is in no buffer or string (*note
4359 Detached Extents::).
4361 -- Function: delete-extent extent
4362 This function removes EXTENT from its buffer and destroys it.
4363 This does not modify the buffer's text, only its display
4364 properties. The extent cannot be used thereafter. To remove an
4365 extent in such a way that it can be re-inserted later, use
4366 `detach-extent'. *Note Detached Extents::.
4368 -- Function: extent-object extent
4369 This function returns the buffer or string that EXTENT is in. If
4370 the return value is `nil', this means that the extent is detached;
4371 however, a detached extent will not necessarily return a value of
4374 -- Function: extent-live-p object
4375 This function returns `t' if OBJECT is an extent that has not been
4376 deleted, and `nil' otherwise.
4379 File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents
4381 47.3 Extent Endpoints
4382 =====================
4384 Every extent has a start position and an end position, and logically
4385 affects the characters between those positions. Normally the start and
4386 end positions must both be valid positions in the extent's buffer or
4387 string. However, both endpoints can be `nil', meaning the extent is
4388 detached. *Note Detached Extents::.
4390 Whether the extent overlaps its endpoints is governed by its
4391 `start-open' and `end-open' properties. Insertion of a character at a
4392 closed endpoint will expand the extent to include that character;
4393 insertion at an open endpoint will not. Similarly, functions such as
4394 `extent-at' that scan over all extents overlapping a particular
4395 position will include extents with a closed endpoint at that position,
4396 but not extents with an open endpoint.
4398 Note that the `start-closed' and `end-closed' properties are
4399 equivalent to `start-open' and `end-open' with the opposite sense.
4401 Both endpoints can be equal, in which case the extent includes no
4402 characters but still exists in the buffer or string. Zero-length
4403 extents are used to represent annotations (*note Annotations::) and can
4404 be used as a more powerful form of a marker. Deletion of all the
4405 characters in an extent may or may not result in a zero-length extent;
4406 this depends on the `detachable' property (*note Detached Extents::).
4407 Insertion at the position of a zero-length extent expands the extent if
4408 both endpoints are closed; goes before the extent if it has the
4409 `start-open' property; and goes after the extent if it has the
4410 `end-open' property. Zero-length extents with both the `start-open'
4411 and `end-open' properties are treated as if their starting point were
4412 closed. Deletion of a character on a side of a zero-length extent
4413 whose corresponding endpoint is closed causes the extent to be detached
4414 if its `detachable' property is set; if the corresponding endpoint is
4415 open, the extent remains in the buffer, moving as necessary.
4417 Extents are ordered within a buffer or string by increasing start
4418 position, and then by decreasing end position (this is called the
4421 -- Function: extent-start-position extent
4422 This function returns the start position of EXTENT.
4424 -- Function: extent-end-position extent
4425 This function returns the end position of EXTENT.
4427 -- Function: extent-length extent
4428 This function returns the length of EXTENT in characters. If the
4429 extent is detached, this returns `0'. If the extent is not
4430 detached, this is equivalent to
4431 (- (extent-end-position EXTENT) (extent-start-position EXTENT))
4433 -- Function: set-extent-endpoints extent start end &optional
4435 This function sets the start and end position of EXTENT to START
4436 and END. If both are `nil', this is equivalent to `detach-extent'.
4438 BUFFER-OR-STRING specifies the new buffer or string that the
4439 extent should be in, and defaults to EXTENT's buffer or string.
4440 (If `nil', and EXTENT is in no buffer and no string, it defaults
4441 to the current buffer.)
4443 See documentation on `detach-extent' for a discussion of undo
4447 File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents
4449 47.4 Finding Extents
4450 ====================
4452 The following functions provide a simple way of determining the extents
4453 in a buffer or string. A number of more sophisticated primitives for
4454 mapping over the extents in a range of a buffer or string are also
4455 provided (*note Mapping Over Extents::). When reading through this
4456 section, keep in mind the way that extents are ordered (*note Extent
4459 -- Function: extent-list &optional buffer-or-string from to flags
4461 This function returns a list of the extents in BUFFER-OR-STRING.
4462 BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
4463 and TO can be used to limit the range over which extents are
4464 returned; if omitted, all extents in the buffer or string are
4467 More specifically, if a range is specified using FROM and TO, only
4468 extents that overlap the range (i.e. begin or end inside of the
4469 range) are included in the list. FROM and TO default to the
4470 beginning and end of BUFFER-OR-STRING, respectively.
4472 FLAGS controls how end cases are treated. For a discussion of
4473 this, and exactly what "overlap" means, see `map-extents'.
4475 The optional arguments PROPERTY and VALUE can be used to further
4476 restrict which extents are returned. They have the same meaning
4477 as for `map-extents'.
4479 If you want to map a function over the extents in a buffer or
4480 string, consider using `map-extents' or `mapcar-extents' instead.
4482 See also the function `extents-at'.
4484 Functions that create extents must be prepared for the possibility
4485 that there are other extents in the same area, created by other
4486 functions. To deal with this, functions typically mark their own
4487 extents by setting a particular property on them. The following
4488 function makes it easier to locate those extents.
4490 -- Function: extent-at pos &optional object property before at-flag
4491 This function finds the "smallest" extent (i.e., the last one in
4492 the display order) at (i.e., overlapping) POS in OBJECT (a buffer
4493 or string) having PROPERTY set. OBJECT defaults to the current
4494 buffer. PROPERTY defaults to `nil', meaning that any extent will
4495 do. Returns `nil' if there is no matching extent at POS. If the
4496 fourth argument BEFORE is not `nil', it must be an extent; any
4497 returned extent will precede that extent. This feature allows
4498 `extent-at' to be used by a loop over extents.
4500 AT-FLAG controls how end cases are handled (i.e. what "at" really
4501 means), and should be one of:
4506 An extent is at POS if it covers the character after POS.
4507 This is consistent with the way that text properties work.
4510 An extent is at POS if it covers the character before POS.
4513 An extent is at POS if it overlaps or abuts POS. This
4514 includes all zero-length extents at POS.
4516 Note that in all cases, the start-openness and end-openness of the
4517 extents considered is ignored. If you want to pay attention to
4518 those properties, you should use `map-extents', which gives you
4521 The following low-level functions are provided for explicitly
4522 traversing the extents in a buffer according to the display order.
4523 These functions are mostly intended for debugging--in normal operation,
4524 you should probably use `mapcar-extents' or `map-extents', or loop
4525 using the BEFORE argument to `extent-at', rather than creating a loop
4526 using `next-extent'.
4528 -- Function: next-extent extent
4529 Given an extent EXTENT, this function returns the next extent in
4530 the buffer or string's display order. If EXTENT is a buffer or
4531 string, this returns the first extent in the buffer or string.
4533 -- Function: previous-extent extent
4534 Given an extent EXTENT, this function returns the previous extent
4535 in the buffer or string's display order. If EXTENT is a buffer or
4536 string, this returns the last extent in the buffer or string.
4539 File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents
4541 47.5 Mapping Over Extents
4542 =========================
4544 The most basic and general function for mapping over extents is called
4545 `map-extents'. You should read through the definition of this function
4546 to familiarize yourself with the concepts and optional arguments
4547 involved. However, in practice you may find it more convenient to use
4548 the function `mapcar-extents' or to create a loop using the `before'
4549 argument to `extent-at' (*note Finding Extents::).
4551 -- Function: map-extents function &optional object from to maparg
4552 flags property value
4553 This function maps FUNCTION over the extents which overlap a
4554 region in OBJECT. OBJECT is normally a buffer or string but could
4555 be an extent (see below). The region is normally bounded by
4556 [FROM, TO) (i.e. the beginning of the region is closed and the end
4557 of the region is open), but this can be changed with the FLAGS
4558 argument (see below for a complete discussion).
4560 FUNCTION is called with the arguments (extent, MAPARG). The
4561 arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
4562 default to the current buffer, the beginning of OBJECT, the end of
4563 OBJECT, `nil', and `nil', respectively. `map-extents' returns the
4564 first non-`nil' result produced by FUNCTION, and no more calls to
4565 FUNCTION are made after it returns non-`nil'.
4567 If OBJECT is an extent, FROM and TO default to the extent's
4568 endpoints, and the mapping omits that extent and its predecessors.
4569 This feature supports restarting a loop based on `map-extents'.
4570 Note: OBJECT must be attached to a buffer or string, and the
4571 mapping is done over that buffer or string.
4573 An extent overlaps the region if there is any point in the extent
4574 that is also in the region. (For the purpose of overlap,
4575 zero-length extents and regions are treated as closed on both ends
4576 regardless of their endpoints' specified open/closedness.) Note
4577 that the endpoints of an extent or region are considered to be in
4578 that extent or region if and only if the corresponding end is
4579 closed. For example, the extent [5,7] overlaps the region [2,5]
4580 because 5 is in both the extent and the region. However, (5,7]
4581 does not overlap [2,5] because 5 is not in the extent, and neither
4582 [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
4585 The optional FLAGS can be a symbol or a list of one or more
4586 symbols, modifying the behavior of `map-extents'. Allowed symbols
4590 The region's end is closed.
4593 The region's start is open.
4595 `all-extents-closed'
4596 Treat all extents as closed on both ends for the purpose of
4597 determining whether they overlap the region, irrespective of
4598 their actual open- or closedness.
4601 Treat all extents as open on both ends.
4603 `all-extents-closed-open'
4604 Treat all extents as start-closed, end-open.
4606 `all-extents-open-closed'
4607 Treat all extents as start-open, end-closed.
4610 In addition to the above conditions for extent overlap, the
4611 extent's start position must lie within the specified region.
4612 Note that, for this condition, open start positions are
4613 treated as if 0.5 was added to the endpoint's value, and open
4614 end positions are treated as if 0.5 was subtracted from the
4618 The extent's end position must lie within the region.
4620 `start-and-end-in-region'
4621 Both the extent's start and end positions must lie within the
4624 `start-or-end-in-region'
4625 Either the extent's start or end position must lie within the
4629 The condition specified by a `*-in-region' flag must _not_
4630 hold for the extent to be considered.
4632 At most one of `all-extents-closed', `all-extents-open',
4633 `all-extents-closed-open', and `all-extents-open-closed' may be
4636 At most one of `start-in-region', `end-in-region',
4637 `start-and-end-in-region', and `start-or-end-in-region' may be
4640 If optional arg PROPERTY is non-`nil', only extents with that
4641 property set on them will be visited. If optional arg VALUE is
4642 non-`nil', only extents whose value for that property is `eq' to
4643 VALUE will be visited.
4645 If you want to map over extents and accumulate a list of results,
4646 the following function may be more convenient than `map-extents'.
4648 -- Function: mapcar-extents function &optional predicate
4649 buffer-or-string from to flags property value
4650 This function applies FUNCTION to all extents which overlap a
4651 region in BUFFER-OR-STRING. The region is delimited by FROM and
4652 TO. FUNCTION is called with one argument, the extent. A list of
4653 the values returned by FUNCTION is returned. An optional
4654 PREDICATE may be used to further limit the extents over which
4655 FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and
4656 VALUE may also be used to control the extents passed to PREDICATE
4657 or FUNCTION, and have the same meaning as in `map-extents'.
4659 -- Function: map-extent-children function &optional object from to
4660 maparg flags property value
4661 This function is similar to `map-extents', but differs in that:
4663 * It only visits extents which start in the given region.
4665 * After visiting an extent E, it skips all other extents which
4666 start inside E but end before E's end.
4668 Thus, this function may be used to walk a tree of extents in a
4670 (defun walk-extents (buffer &optional ignore)
4671 (map-extent-children 'walk-extents buffer))
4673 -- Function: extent-in-region-p extent &optional from to flags
4674 This function returns `t' if `map-extents' would visit EXTENT if
4675 called with the given arguments.
4678 File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
4680 47.6 Properties of Extents
4681 ==========================
4683 Each extent has a property list associating property names with values.
4684 Some property names have predefined meanings, and can usually only
4685 assume particular values. Assigning other values to such a property
4686 either cause the value to be converted into a legal value (e.g.,
4687 assigning anything but `nil' to a Boolean property will cause the value
4688 of `t' to be assigned to the property) or will cause an error.
4689 Property names without predefined meanings can be assigned any value.
4690 An undefined property is equivalent to a property with a value of
4691 `nil', or with a particular default value in the case of properties
4692 with predefined meanings. Note that, when an extent is created, the
4693 `end-open' and `detachable' properties are set on it.
4695 If an extent has a parent, all of its properties actually derive
4696 from that parent (or from the root ancestor if the parent in turn has a
4697 parent), and setting a property of the extent actually sets that
4698 property on the parent. *Note Extent Parents::.
4700 -- Function: extent-property extent property &optional default
4701 This function returns EXTENT's value for PROPERTY, or DEFAULT if
4702 no such property exists.
4704 -- Function: extent-properties extent
4705 This function returns a list of all of EXTENT's properties that do
4706 not have the value of `nil' (or the default value, for properties
4707 with predefined meanings).
4709 -- Function: set-extent-property extent property value
4710 This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
4711 predefined meaning, only certain values are allowed, and some
4712 values may be converted to others before being stored.)
4714 -- Function: set-extent-properties extent plist
4715 Change some properties of EXTENT. PLIST is a property list. This
4716 is useful to change many extent properties at once.
4718 The following table lists the properties with predefined meanings,
4719 along with their allowable values.
4722 (Boolean) Whether the extent is detached. Setting this is the
4723 same as calling `detach-extent'. *Note Detached Extents::.
4726 (Boolean) Whether the extent has been deleted. Setting this is
4727 the same as calling `delete-extent'.
4730 (integer) The extent's redisplay priority. Defaults to 0. *Note
4731 priority: Intro to Extents. This property can also be set with
4732 `set-extent-priority' and accessed with `extent-priority'.
4735 (Boolean) Whether the start position of the extent is open,
4736 meaning that characters inserted at that position go outside of
4737 the extent. *Note Extent Endpoints::.
4740 (Boolean) Same as `start-open' but with the opposite sense.
4741 Setting this property clears `start-open' and vice-versa.
4744 (Boolean) Whether the end position of the extent is open, meaning
4745 that characters inserted at that position go outside of the
4746 extent. This is `t' by default. *Note Extent Endpoints::.
4749 (Boolean) Same as `end-open' but with the opposite sense. Setting
4750 this property clears `end-open' and vice-versa.
4753 (Boolean) Whether text within this extent will be unmodifiable.
4756 (face, face name, list of faces or face names, or `nil') The face
4757 in which to display the extent's text. This property can also be
4758 set with `set-extent-face' and accessed with `extent-face'. Note
4759 that if a list of faces is specified, the faces are merged
4760 together, with faces earlier in the list having priority over
4761 faces later in the list.
4764 (face, face name, list of faces or face names, or `nil') The face
4765 used to display the extent when the mouse moves over it. This
4766 property can also be set with `set-extent-mouse-face' and accessed
4767 with `extent-mouse-face'. Note that if a list of faces is
4768 specified, the faces are merged together, with faces earlier in
4769 the list having priority over faces later in the list. *Note
4770 Extents and Events::.
4773 (pointer glyph) The glyph used as the pointer when the mouse
4774 moves over the extent. This takes precedence over the
4775 `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
4776 for any reason this glyph is an invalid pointer, the standard
4777 glyphs will be used as fallbacks. *Note External Glyphs::.
4780 (Boolean) Whether this extent becomes detached when all of the
4781 text it covers is deleted. This is `t' by default. *Note
4785 (Boolean) Whether this extent should be copied into strings, so
4786 that kill, yank, and undo commands will restore or copy it. *Note
4787 Duplicable Extents::.
4790 (Boolean) Meaningful only in conjunction with `duplicable'. When
4791 this is set, there may be only one instance of this extent
4792 attached at a time. *Note Duplicable Extents::.
4795 (Boolean) If `t', text under this extent will not be displayed -
4796 it will look as if the text and the begin-glyph is not there at
4797 all. The end-glyph will still be displayed.
4800 (keymap or `nil') This keymap is consulted for mouse clicks on this
4801 extent or keypresses made while `point' is within the extent.
4802 *Note Extents and Events::.
4805 This is a hook that is run when a duplicable extent is about to be
4806 copied from a buffer to a string (or the kill ring). *Note
4807 Duplicable Extents::.
4810 This is a hook that is run when a duplicable extent is about to be
4811 copied from a string (or the kill ring) into a buffer. *Note
4812 Duplicable Extents::.
4815 (glyph or `nil') This extent's begin glyph. *Note Annotations::.
4818 (glyph or `nil') This extent's end glyph. *Note Annotations::.
4820 `begin-glyph-layout'
4821 (`text', `whitespace', `inside-margin', or `outside-margin') The
4822 layout policy for this extent's begin glyph. Defaults to `text'.
4823 *Note Annotations::.
4826 (`text', `whitespace', `inside-margin', or `outside-margin') The
4827 layout policy for this extent's end glyph. Defaults to `text'.
4828 *Note Annotations::.
4830 `initial-redisplay-function'
4831 (any funcallable object) The function to be called the first time
4832 (a part of) the extent is redisplayed. It will be called with the
4833 extent as its argument.
4835 This is used by `lazy-shot' to implement lazy font-locking. The
4836 functionality is still experimental, and may change without further
4839 The following convenience functions are provided for accessing
4840 particular properties of an extent.
4842 -- Function: extent-face extent
4843 This function returns the `face' property of EXTENT. This might
4844 also return a list of face names. Do not modify this list
4845 directly! Instead, use `set-extent-face'.
4847 Note that you can use `eq' to compare lists of faces as returned
4848 by `extent-face'. In other words, if you set the face of two
4849 different extents to two lists that are `equal' but not `eq', then
4850 the return value of `extent-face' on the two extents will return
4853 -- Function: extent-mouse-face extent
4854 This function returns the `mouse-face' property of EXTENT. This
4855 might also return a list of face names. Do not modify this list
4856 directly! Instead, use `set-extent-mouse-face'.
4858 Note that you can use `eq' to compare lists of faces as returned
4859 by `extent-mouse-face', just like for `extent-face'.
4861 -- Function: extent-priority extent
4862 This function returns the `priority' property of EXTENT.
4864 -- Function: extent-keymap extent
4865 This function returns the `keymap' property of EXTENT.
4867 -- Function: extent-begin-glyph-layout extent
4868 This function returns the `begin-glyph-layout' property of EXTENT,
4869 i.e. the layout policy associated with the EXTENT's begin glyph.
4871 -- Function: extent-end-glyph-layout extent
4872 This function returns the `end-glyph-layout' property of EXTENT,
4873 i.e. the layout policy associated with the EXTENT's end glyph.
4875 -- Function: extent-begin-glyph extent
4876 This function returns the `begin-glyph' property of EXTENT, i.e.
4877 the glyph object displayed at the beginning of EXTENT. If there
4878 is none, `nil' is returned.
4880 -- Function: extent-end-glyph extent
4881 This function returns the `end-glyph' property of EXTENT, i.e. the
4882 glyph object displayed at the end of EXTENT. If there is none,
4885 The following convenience functions are provided for setting
4886 particular properties of an extent.
4888 -- Function: set-extent-priority extent priority
4889 This function sets the `priority' property of EXTENT to PRIORITY.
4891 -- Function: set-extent-face extent face
4892 This function sets the `face' property of EXTENT to FACE.
4894 -- Function: set-extent-mouse-face extent face
4895 This function sets the `mouse-face' property of EXTENT to FACE.
4897 -- Function: set-extent-keymap extent keymap
4898 This function sets the `keymap' property of EXTENT to KEYMAP.
4899 KEYMAP must be either a keymap object, or `nil'.
4901 -- Function: set-extent-begin-glyph-layout extent layout
4902 This function sets the `begin-glyph-layout' property of EXTENT to
4905 -- Function: set-extent-end-glyph-layout extent layout
4906 This function sets the `end-glyph-layout' property of EXTENT to
4909 -- Function: set-extent-begin-glyph extent begin-glyph &optional layout
4910 This function sets the `begin-glyph' and `glyph-layout' properties
4911 of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
4912 defaults to `text' if not specified.)
4914 -- Function: set-extent-end-glyph extent end-glyph &optional layout
4915 This function sets the `end-glyph' and `glyph-layout' properties
4916 of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
4917 to `text' if not specified.)
4919 -- Function: set-extent-initial-redisplay-function extent function
4920 This function sets the `initial-redisplay-function' property of the
4924 File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
4926 47.7 Detached Extents
4927 =====================
4929 A detached extent is an extent that is not attached to a buffer or
4930 string but can be re-inserted. Detached extents have a start position
4931 and end position of `nil'. Extents can be explicitly detached using
4932 `detach-extent'. An extent is also detached when all of its characters
4933 are all killed by a deletion, if its `detachable' property is set; if
4934 this property is not set, the extent becomes a zero-length extent.
4935 (Zero-length extents with the `detachable' property set behave
4936 specially. *Note zero-length extents: Extent Endpoints.)
4938 -- Function: detach-extent extent
4939 This function detaches EXTENT from its buffer or string. If
4940 EXTENT has the `duplicable' property, its detachment is tracked by
4941 the undo mechanism. *Note Duplicable Extents::.
4943 -- Function: extent-detached-p extent
4944 This function returns `nil' if EXTENT is detached, and `t'
4947 -- Function: copy-extent extent &optional object
4948 This function makes a copy of EXTENT. It is initially detached.
4949 Optional argument OBJECT defaults to EXTENT's object (normally a
4950 buffer or string, but could be `nil').
4952 -- Function: insert-extent extent &optional start end no-hooks object
4953 This function inserts EXTENT from START to END in OBJECT (a buffer
4954 or string). If EXTENT is detached from a different buffer or
4955 string, or in most cases when EXTENT is already attached, the
4956 extent will first be copied as if with `copy-extent'. This
4957 function operates the same as if `insert' were called on a string
4958 whose extent data calls for EXTENT to be inserted, except that if
4959 NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
4960 invoked. *Note Duplicable Extents::.
4963 File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
4968 An extent can have a parent extent set for it. If this is the case,
4969 the extent derives all its properties from that extent and has no
4970 properties of its own. The only "properties" that the extent keeps are
4971 the buffer or string it refers to and the start and end points. (More
4972 correctly, the extent's own properties are shadowed. If you later
4973 change the extent to have no parent, its own properties will become
4976 It is possible for an extent's parent to itself have a parent, and
4977 so on. Through this, a whole tree of extents can be created, all
4978 deriving their properties from one root extent. Note, however, that
4979 you cannot create an inheritance loop--this is explicitly disallowed.
4981 Parent extents are used to implement the extents over the modeline.
4983 -- Function: set-extent-parent extent parent
4984 This function sets the parent of EXTENT to PARENT. If PARENT is
4985 `nil', the extent is set to have no parent.
4987 -- Function: extent-parent extent
4988 This function return the parents (if any) of EXTENT, or `nil'.
4990 -- Function: extent-children extent
4991 This function returns a list of the children (if any) of EXTENT.
4992 The children of an extent are all those extents whose parent is
4993 that extent. This function does not recursively trace children of
4996 -- Function: extent-descendants extent
4997 This function returns a list of all descendants of EXTENT,
4998 including EXTENT. This recursively applies `extent-children' to
4999 any children of EXTENT, until no more children can be found.
5002 File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
5004 47.9 Duplicable Extents
5005 =======================
5007 If an extent has the `duplicable' property, it will be copied into
5008 strings, so that kill, yank, and undo commands will restore or copy it.
5012 * When a string is created using `buffer-substring' or
5013 `buffer-string', any duplicable extents in the region corresponding
5014 to the string will be copied into the string (*note Buffer
5015 Contents::). When the string is inserted into a buffer using
5016 `insert', `insert-before-markers', `insert-buffer' or
5017 `insert-buffer-substring', the extents in the string will be copied
5018 back into the buffer (*note Insertion::). The extents in a string
5019 can, of course, be retrieved explicitly using the standard extent
5020 primitives over the string.
5022 * Similarly, when text is copied or cut into the kill ring, any
5023 duplicable extents will be remembered and reinserted later when
5024 the text is pasted back into a buffer.
5026 * When `concat' is called on strings, the extents in the strings are
5027 copied into the resulting string.
5029 * When `substring' is called on a string, the relevant extents are
5030 copied into the resulting string.
5032 * When a duplicable extent is detached by `detach-extent' or string
5033 deletion, or inserted by `insert-extent' or string insertion, the
5034 action is recorded by the undo mechanism so that it can be undone
5035 later. Note that if an extent gets detached and then a later undo
5036 causes the extent to get reinserted, the new extent will not be
5037 `eq' to the original extent.
5039 * Extent motion, face changes, and attachment via `make-extent' are
5040 not recorded by the undo mechanism. This means that extent changes
5041 which are to be undo-able must be performed by character editing,
5042 or by insertion and detachment of duplicable extents.
5044 * A duplicable extent's `copy-function' property, if non-`nil',
5045 should be a function, and will be run when a duplicable extent is
5046 about to be copied from a buffer to a string (or the kill ring).
5047 It is called with three arguments: the extent and the buffer
5048 positions within it which are being copied. If this function
5049 returns `nil', then the extent will not be copied; otherwise it
5052 * A duplicable extent's `paste-function' property, if non-`nil',
5053 should be a function, and will be run when a duplicable extent is
5054 about to be copied from a string (or the kill ring) into a buffer.
5055 It is called with three arguments: the original extent and the
5056 buffer positions which the copied extent will occupy. (This hook
5057 is run after the corresponding text has already been inserted into
5058 the buffer.) Note that the extent argument may be detached when
5059 this function is run. If this function returns `nil', no extent
5060 will be inserted. Otherwise, there will be an extent covering the
5063 Note: if the extent to be copied is already attached to the buffer
5064 and overlaps the new range, the extent will simply be extended and
5065 the `paste-function' will not be called.
5068 File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
5070 47.10 Interaction of Extents with Keyboard and Mouse Events
5071 ===========================================================
5073 If an extent has the `mouse-face' property set, it will be highlighted
5074 when the mouse passes over it. This includes the begin-glyph, but not
5075 the end-glyph. Highlighting is accomplished by merging the extent's
5076 face with the face or faces specified by the `mouse-face' property.
5077 The effect is as if a pseudo-extent with the `mouse-face' face were
5078 inserted after the extent in the display order (*note Extent
5079 Endpoints::, display order).
5081 -- Variable: mouse-highlight-priority
5082 This variable holds the priority to use when merging in the
5083 highlighting pseudo-extent. The default is 1000. This is
5084 purposely set very high so that the highlighting pseudo-extent
5085 shows up even if there are other extents with various priorities
5086 at the same location.
5088 You can also explicitly cause an extent to be highlighted. Only one
5089 extent at a time can be highlighted in this fashion, and any other
5090 highlighted extent will be de-highlighted.
5092 -- Function: highlight-extent extent &optional highlight-p
5093 This function highlights (if HIGHLIGHT-P is non-`nil') or
5094 de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
5095 `mouse-face' property. (Nothing happens if EXTENT does not have
5096 the `mouse-face' property.)
5098 -- Function: force-highlight-extent extent &optional highlight-p
5099 This function is similar to `highlight-extent' but highlights or
5100 de-highlights the extent regardless of whether it has the
5101 `mouse-face' property.
5103 If an extent has a `keymap' property, this keymap will be consulted
5104 for mouse clicks on the extent and keypresses made while `point' is
5105 within the extent. The behavior of mouse clicks and keystrokes not
5106 defined in the keymap is as normal for the buffer.
5109 File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
5111 47.11 Atomic Extents
5112 ====================
5114 If the Lisp file `atomic-extents' is loaded, then the atomic extent
5115 facility is available. An "atomic extent" is an extent for which
5116 `point' cannot be positioned anywhere within it. This ensures that
5117 when selecting text, either all or none of the extent is selected.
5119 To make an extent atomic, set its `atomic' property.
5122 File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
5127 A specifier is an object used to keep track of a property whose value
5128 should vary according to _display context_, a window, a frame, or
5129 device. The value of many built-in properties, such as the font,
5130 foreground, background, and such properties of a face and variables
5131 such as `modeline-shadow-thickness' and `top-toolbar-height', is
5132 actually a specifier object. The specifier object, in turn, is
5133 "instanced" in a particular situation to yield the real value of the
5134 property in the current context.
5136 -- Function: specifierp object
5137 This function returns non-`nil' if OBJECT is a specifier.
5141 * Introduction to Specifiers:: Specifiers provide a clean way for
5142 display and other properties to vary
5143 (under user control) in a wide variety
5145 * Simple Specifier Usage:: Getting started with specifiers.
5146 * Specifiers In-Depth:: Gory details about specifier innards.
5147 * Specifier Instancing:: Instancing means obtaining the ``value'' of
5148 a specifier in a particular context.
5149 * Specifier Types:: Specifiers come in different flavors.
5150 * Adding Specifications:: Specifications control a specifier's ``value''
5151 by giving conditions under which a
5152 particular value is valid.
5153 * Retrieving Specifications:: Querying a specifier's specifications.
5154 * Specifier Tag Functions:: Working with specifier tags.
5155 * Specifier Instancing Functions::
5156 Functions to instance a specifier.
5157 * Specifier Examples:: Making all this stuff clearer.
5158 * Creating Specifiers:: Creating specifiers for your own use.
5159 * Specifier Validation Functions::
5160 Validating the components of a specifier.
5161 * Other Specification Functions::
5162 Other ways of working with specifications.
5165 File: lispref.info, Node: Introduction to Specifiers, Next: Simple Specifier Usage, Up: Specifiers
5167 48.1 Introduction to Specifiers
5168 ===============================
5170 Perhaps the most useful way to explain specifiers is via an analogy.
5171 Emacs Lisp programmers are used to _buffer-local variables_ *Note
5172 Buffer-Local Variables::. For example, the variable `modeline-format',
5173 which controls the format of the modeline, can have different values
5174 depending on the particular buffer being edited. The variable has a
5175 default value which most modes will use, but a specialized package such
5176 as Calendar might change the variable so as to tailor the modeline to
5177 its own purposes. Other variables are perhaps best thought of as "mode
5178 local," such as font-lock keywords, but they are implemented as buffer
5181 Other properties (such as those that can be changed by the
5182 `modify-frame-parameters' function, for example the color of the text
5183 cursor) can have frame-local values, although it might also make sense
5184 for them to have buffer-local values. In other cases, you might want
5185 the property to vary depending on the particular window within the
5186 frame that applies (e.g. the top or bottom window in a split frame), the
5187 device type that that frame appears on (X or tty), etc. Perhaps you can
5188 envision some more complicated scenario where you want a particular
5189 value in a specified buffer, another value in all other buffers
5190 displayed on a particular frame, another value in all other buffers
5191 displayed in all other frames on any mono (two-color, e.g. black and
5192 white only) displays, and a default value in all other circumstances.
5194 Specifiers generalize both buffer- and frame-local properties.
5195 Specifiers vary according to the _display_ context. Font-lock keywords
5196 in a buffer will be the same no matter which window the buffer is
5197 displayed in, but windows on TTY devices will simply not be capable of
5198 the flexibility that windows on modern GUI devices are. Specifiers
5199 provide a way for the programmer to _declare_ that an emphasized text
5200 should be italic on GUI devices and inverse video on TTYs. They also
5201 provide a way for the programmer to declare fallbacks, so that a color
5202 specified as "chartreuse" where possible can fall back to "yellow" on
5203 devices where only ANSI (4-bit) color is available. The complex
5204 calculations and device querying are transparent to both user and
5205 programmer. You ask for what you want; it's up to XEmacs to provide
5206 it, or a reasonable approximation.
5208 We call such a declaration a "specification". A "specification"
5209 applies in a particular "locale", which is a window, buffer, frame,
5210 device, or the global locale. The value part of the specification is
5211 called an "instantiator". The process of determining the value in a
5212 particular context, or "domain", is called "instantiation" or
5213 "instancing". A domain is a window, frame, or device.
5215 The difference between "locale" and "domain" is somewhat subtle.
5216 You may think of a locale as a class of domains, which may span
5217 different devices. Since the specification is abstract (a Lisp form),
5218 you can state it without reference to a device. On the other hand, when
5219 you instantiate a specification, you must know the type of the device.
5220 It is useless to specify that "blue means emphasis" on a monochrome
5221 device. Thus instantiation requires specification of the device on
5222 which it will be rendered.
5224 Thus a "specifier" allows a great deal of flexibility in controlling
5225 exactly what value a property has in which circumstances. Specifiers
5226 are most commonly used for display properties, such as an image or the
5227 foreground color of a face. As a simple example, you can specify that
5228 the foreground of the default face be
5230 * blue for a particular buffer
5232 * green for all other buffers
5234 As a more complicated example, you could specify that the foreground
5235 of the default face be
5237 * forest green for all buffers displayed in a particular Emacs
5238 window, or green if the X server doesn't recognize the color
5241 * blue for all buffers displayed in a particular frame
5243 * red for all other buffers displayed on a color device
5245 * white for all other buffers
5248 File: lispref.info, Node: Simple Specifier Usage, Next: Specifiers In-Depth, Prev: Introduction to Specifiers, Up: Specifiers
5250 48.2 Simple Specifier Usage
5251 ===========================
5253 A useful specifier application is adding a button to a toolbar. XEmacs
5254 provides several toolbars, one along each edge of the frame. Normally
5255 only one is used at a time, the default. The default toolbar is
5256 actually a specifier object which is the value of `default-toolbar'.
5257 *Note Toolbar Intro::.
5259 The specification of a toolbar is simple: it is a list of buttons.
5260 Each button is a vector with four elements: an icon, a command, the
5261 enabled flag, and a help string. Let's retrieve the instance of the
5262 toolbar you see in the selected frame.
5264 (specifier-instance default-toolbar)
5266 The value returned is, as promised, a list of vectors. Now let's
5267 build up a button, and add it to the toolbar. Our button will invoke
5268 the last defined keyboard macro. This is an alternative to
5269 `name-last-kbd-macro' for creating a persistent macro, rather than an
5272 A toolbar button icon can be quite sophisticated, with different
5273 images for button up, button down, and disabled states, and a similar
5274 set with captions. We'll use a very simple icon, but we have to jump
5275 through a few non-obvious hoops designed to support the sophisticated
5276 applications. The rest of the button descriptor is straightforward.
5278 (setq toolbar-my-kbd-macro-button
5279 `[ (list (make-glyph "MyKbdMac"))
5280 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
5282 "Execute a previously defined keyboard macro." ])
5284 (set-specifier default-toolbar
5285 (cons toolbar-my-kbd-macro-button
5286 (specifier-specs default-toolbar 'global))
5289 To remove the button, just substitute the function `delete' for the
5292 What is the difference between `specifier-instance', which we used
5293 in the example of retrieving the toolbar descriptor, and
5294 `specifier-specs', which was used in the toolbar manipulating code?
5295 `specifier-specs' retrieves a copy of the instantiator, which is
5296 abstract and does not depend on context. `specifier-instance', on the
5297 other hand, actually instantiates the specification, and returns the
5298 result for the given context. Another way to express this is:
5299 `specifier-specs' takes a _locale_ as an argument, while
5300 `specifier-instance' takes a _domain_. The reason for providing
5301 `specifier-instance' is that sometimes you wish to see the object that
5302 XEmacs will actually use. `specifier-specs', on the other hand, shows
5303 you what the programmer (or user) requested. When a program
5304 manipulates specifications, clearly it's the latter that is desirable.
5306 In the case of the toolbar descriptor, it turns out that these are
5307 the same: the instancing process is trivial. However, many
5308 specifications have non-trivial instancing. Compare the results of the
5309 following forms on my system. (The `(cdr (first ...))' form is due to
5310 my use of Mule. On non-Mule XEmacsen, just use `specifier-specs'.)
5312 (cdr (first (specifier-specs (face-font 'default) 'global)))
5313 => "-*--14-*jisx0208*-0"
5315 (specifier-instance (face-font 'default))
5316 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
5318 In this case, `specifier-instance' returns an opaque object;
5319 programs can't work on it, they can only pass it around. Worse, in some
5320 environments the instantiation will fail, resulting in a different value
5321 (when another instantiation succeeds), or worse yet, an error, if all
5322 attempts to instance the specifier fail. `specifier-instance' is
5323 context-dependent, even for the exact same specification.
5324 `specifier-specs' is deterministic, and only depends on the
5327 Note that in the toolbar-changing code we operate in the global
5328 locale. This means that narrower locales, if they have specifications,
5329 will shadow our changes. (Specifier instancing does not merge
5330 specifications. It selects the "highest-priority successful
5331 specification" and instances that.)
5333 In fact, in our example, it seems pretty likely that different
5334 buffers _should_ have different buttons. (The icon can be the same, but
5335 the keyboard macro you create in a Dired buffer is highly unlikely to be
5336 useful in a LaTeX buffer!) Here's one way to implement this:
5338 (setq toolbar-my-kbd-macro-button
5339 `[ (list (make-glyph "MyKbdMac"))
5340 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
5342 "Execute a previously defined keyboard macro." ])
5344 (set-specifier default-toolbar
5345 (cons toolbar-my-kbd-macro-button
5346 (cond ((specifier-specs default-toolbar
5348 ((specifier-specs default-toolbar
5352 Finally, a cautionary note: the use of `specifier-specs' in the code
5353 above is for expository purposes. Don't use it in production code. In
5354 fact, the `set-specifier' form above is likely to fail occasionally,
5355 because you can add many specifications for the same locale.
5357 In these cases, `specifier-specs' will return a list. A further
5358 refinement is that a specification may be associated with a set of
5359 "specifier tags". If the list of specifier tags is non-nil, then
5360 `specifier-specs' will return a cons of the tag set and the
5361 instantiator. Evidently `specifier-specs' is a bit unreliable. (For
5362 toolbars, the code above should work 99% of the time, because toolbars
5363 are rarely changed. Since instantiation is trivial, multiple specs are
5364 not useful--the first one always succeeds.)
5366 In fact, `specifier-specs' is intended to be used to display specs
5367 to humans with a minimum of clutter. The robust way to access
5368 specifications is via `specifier-spec-list'. *Note Adding
5369 Specifications::, for the definition of "spec-list". *Note Retrieving
5370 Specifications::, for documentation of `specifier-specs' and
5371 `specifier-spec-list'. To get the desired effect, replace the form
5372 `(specifier-spec default-toolbar 'global)' with
5374 (cdr (second (first (specifier-spec-list default-toolbar 'global))))
5376 (It should be obvious why the example uses the lazy unreliable
5380 File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Simple Specifier Usage, Up: Specifiers
5382 48.3 In-Depth Overview of a Specifier
5383 =====================================
5385 Having variables vary according the editing context is very useful, and
5386 the buffer is the natural "atomic" unit of editing context. In a GUI
5387 environment, it can be similarly useful to have variables whose values
5388 vary according to display context. The atomic unit of display context
5389 is the Emacs window. Buffers are cleanly grouped by modes, but windows
5390 are not so easily pigeonholed. On the one hand, a window displays a
5391 buffer, and thus one possible hierarchy is window, buffer, mode. On the
5392 other, a window is a component of a frame. This generates the window,
5393 frame, device hierarchy. Finally, there are objects such as toolbars
5394 whose properties are described by specifiers. These do not fit
5395 naturally into either hierarchy. This problem is as yet not cleanly
5398 Another potential source of conceptual confusion is the instantiation
5399 process. Instantiating a buffer-local variable is simple: at any given
5400 point in time there is a current buffer, and its local values are used
5401 and set whenever the variable is accessed, unless the programmer goes to
5402 some special effort (uses `default-value' and `set-default'. However,
5403 a specifier object encapsulates a set of "specifications", each of
5404 which says what its value should be if a particular condition applies.
5405 Several such conditions might apply simultaneously in a given window.
5407 For example, one specification might be "The value should be
5408 darkseagreen2 on X devices" another might be "The value should be blue
5409 in the *Help* buffer". So what do we do for "the *Help* buffer on an X
5410 device"? The answer is simple: give each type of locale a priority and
5411 check them in priority order, returning the first instantiator that
5412 successfully instantiates a value.
5414 Given a specifier, a logical question is "What is its value in a
5415 particular situation?" This involves looking through the specifications
5416 to see which ones apply to this particular situation, and perhaps
5417 preferring one over another if more than one applies. In specifier
5418 terminology, a "particular situation" is called a "domain", and
5419 determining its value in a particular domain is called "instancing".
5420 Most of the time, a domain is identified by a particular window. For
5421 example, if the redisplay engine is drawing text in the default face in
5422 a particular window, it retrieves the specifier for the foreground color
5423 of the default face and "instances" it in the domain given by that
5424 window; in other words, it asks the specifier, "What is your value in
5427 Note that the redisplay example is in a sense canonical. That is,
5428 specifiers are designed to present a uniform and _efficient_ API to
5429 redisplay. It is the efficiency constraint that motivates the
5430 introduction of specifier tags, and many restrictions on access (for
5431 example, a buffer is not a domain, and you cannot instantiate a
5432 specifier over a buffer).
5434 More specifically, a specifier contains a set of "specifications",
5435 each of which associates a "locale" (a window object, a buffer object,
5436 a frame object, a device object, or the symbol `global') with an
5437 "inst-list", which is a list of one or more "inst-pairs". (For each
5438 possible locale, there can be at most one specification containing that
5439 locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
5440 zero or more symbols, or "tags") and an "instantiator" (the allowed
5441 form of this varies depending on the type of specifier). In a given
5442 specification, there may be more than one inst-pair with the same tag
5443 set; this is unlike for locales.
5445 The tag set is used to restrict the sorts of devices over which the
5446 instantiator is valid and to uniquely identify instantiators added by a
5447 particular application, so that different applications can work on the
5448 same specifier and not interfere with each other. Each tag can have a
5449 "predicate" associated with it, which is a function of one argument (a
5450 device) that specifies whether the tag matches that particular device.
5451 (If a tag does not have a predicate, it matches all devices.) All tags
5452 in a tag set must match a device for the associated inst-pair to be
5453 instantiable over that device. (A null tag set is perfectly valid, and
5454 trivially matches all devices.)
5456 The valid device types (normally `x', `tty', and `stream') and
5457 device classes (normally `color', `grayscale', and `mono') can always
5458 be used as tags, and match devices of the associated type or class
5459 (*note Consoles and Devices::). User-defined tags may be defined, with
5460 an optional predicate specified. An application can create its own
5461 tag, use it to mark all its instantiators, and be fairly confident that
5462 it will not interfere with other applications that modify the same
5463 specifier--Functions that add a specification to a specifier usually
5464 only overwrite existing inst-pairs with the same tag set as was given,
5465 and a particular tag or tag set can be specified when removing
5468 When a specifier is instanced in a domain, both the locale and the
5469 tag set can be viewed as specifying necessary conditions that must
5470 apply in that domain for an instantiator to be considered as a possible
5471 result of the instancing. More specific locales always override more
5472 general locales (thus, there is no particular ordering of the
5473 specifications in a specifier); however, the tag sets are simply
5474 considered in the order that the inst-pairs occur in the
5475 specification's inst-list.
5477 Note also that the actual object that results from the instancing
5478 (called an "instance object") may not be the same as the instantiator
5479 from which it was derived. For some specifier types (such as integer
5480 specifiers and boolean specifiers), the instantiator will be returned
5481 directly as the instance object. For other types, however, this is not
5482 the case. For example, for font specifiers, the instantiator is a
5483 font-description string and the instance object is a font-instance
5484 object, which describes how the font is displayed on a particular
5485 device. A font-instance object encapsulates such things as the actual
5486 font name used to display the font on that device (a font-description
5487 string under X is usually a wildcard specification that may resolve to
5488 different font names, with possibly different foundries, widths, etc.,
5489 on different devices), the extra properties of that font on that
5490 device, etc. Furthermore, this conversion (called "instantiation")
5491 might fail--a font or color might not exist on a particular device, for
5495 File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
5497 48.4 How a Specifier Is Instanced
5498 =================================
5500 Instancing of a specifier in a particular window domain proceeds as
5503 * First, XEmacs searches for a specification whose locale is the
5504 same as the window. If that fails, the search is repeated,
5505 looking for a locale that is the same as the window's buffer. If
5506 that fails, the search is repeated using the window's frame, then
5507 using the device that frame is on. Finally, the specification
5508 whose locale is the symbol `global' (if there is such a
5509 specification) is considered.
5511 * The inst-pairs contained in the specification that was found are
5512 considered in their order in the inst-list, looking for one whose
5513 tag set matches the device that is derived from the window domain.
5514 (The tag set is an unordered list of zero or more tag symbols.
5515 For all tags that have predicates associated with them, the
5516 predicate must match the device.)
5518 * If a matching tag set is found, the corresponding instantiator is
5519 passed to the specifier's instantiation method, which is specific
5520 to the type of the specifier. If it succeeds, the resulting
5521 instance object is returned as the result of the instancing and
5522 the instancing is done. Otherwise, the operation continues,
5523 looking for another matching inst-pair in the current
5526 * When there are no more inst-pairs to be considered in the current
5527 specification, the search starts over, looking for another
5528 specification as in the first step above.
5530 * If all specifications are exhausted and no instance object can be
5531 derived, the instancing fails. (Actually, this is not completely
5532 true. Some specifier objects for built-in properties have a
5533 "fallback" value, which is either an inst-list or another
5534 specifier object, that is consulted if the instancing is about to
5535 fail. If it is an inst-list, the searching proceeds using the
5536 inst-pairs in that list. If it is a specifier, the entire
5537 instancing starts over using that specifier instead of the given
5538 one. Fallback values are set by the C code and cannot be
5539 modified, except perhaps indirectly, using any Lisp functions.
5540 The purpose of them is to supply some values to make sure that
5541 instancing of built-in properties can't fail and to implement some
5542 basic specifier inheritance, such as the fact that faces inherit
5543 their properties from the `default' face.)
5545 It is also possible to instance a specifier over a frame domain or
5546 device domain instead of over a window domain. The C code, for example,
5547 instances the `top-toolbar-height' variable over a frame domain in
5548 order to determine the height of a frame's top toolbar. Instancing over
5549 a frame or device is similar to instancing over a window except that
5550 specifications for locales that cannot be derived from the domain are
5551 ignored. Specifically, instancing over a frame looks first for frame
5552 locales, then device locales, then the `global' locale. Instancing
5553 over a device domain looks only for device locales and the `global'
5557 File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
5559 48.5 Specifier Types
5560 ====================
5562 There are various different types of specifiers. The type of a
5563 specifier controls what sorts of instantiators are valid, how an
5564 instantiator is instantiated, etc. Here is a list of built-in specifier
5568 The valid instantiators are the symbols `t' and `nil'. Instance
5569 objects are the same as instantiators so no special instantiation
5573 The valid instantiators are integers. Instance objects are the
5574 same as instantiators so no special instantiation function is
5575 needed. `modeline-shadow-thickness' is an example of an integer
5576 specifier (negative thicknesses indicate that the shadow is drawn
5577 recessed instead of raised).
5580 The valid instantiators are natnums (non-negative integers).
5581 Instance objects are the same as instantiators so no special
5582 instantiation function is needed. Natnum specifiers are used for
5583 dimension variables such as `top-toolbar-height'.
5586 All Lisp objects are valid instantiators. Instance objects are
5587 the same as instantiators so no special instantiation function is
5591 The valid instantiators are strings describing fonts or vectors
5592 indicating inheritance from the font of some face. Instance
5593 objects are font-instance objects, which are specific to a
5594 particular device. The instantiation method for font specifiers
5595 can fail, unlike for integer, natnum, boolean, and generic
5599 The valid instantiators are strings describing colors or vectors
5600 indicating inheritance from the foreground or background of some
5601 face. Instance objects are color-instance objects, which are
5602 specific to a particular device. The instantiation method for
5603 color specifiers can fail, as for font specifiers.
5606 Images are perhaps the most complicated type of built-in
5607 specifier. The valid instantiators are strings (a filename,
5608 inline data for a pixmap, or text to be displayed in a text glyph)
5609 or vectors describing inline data of various sorts or indicating
5610 inheritance from the background-pixmap property of some face.
5611 Instance objects are either strings (for text images),
5612 image-instance objects (for pixmap images), or subwindow objects
5613 (for subwindow images). The instantiation method for image
5614 specifiers can fail, as for font and color specifiers.
5617 The valid instantiators are the symbols `t' and `nil' and vectors
5618 indicating inheritance from a boolean property of some face.
5619 Specifiers of this sort are used for all of the built-in boolean
5620 properties of faces. Instance objects are either the symbol `t'
5621 or the symbol `nil'.
5624 The valid instantiators are toolbar descriptors, which are lists
5625 of toolbar-button descriptors (each of which is a vector of two or
5626 four elements). *Note Toolbar::, for more information.
5628 Color and font instance objects can also be used in turn as
5629 instantiators for a new color or font instance object. Since these
5630 instance objects are device-specific, the instantiator can be used
5631 directly as the new instance object, but only if they are of the same
5632 device. If the devices differ, the base color or font of the
5633 instantiating object is effectively used instead as the instantiator.
5635 *Note Faces and Window-System Objects::, for more information on
5636 fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more
5637 information about image specifiers. *Note Toolbar::, for more
5638 information on toolbar specifiers.
5640 -- Function: specifier-type specifier
5641 This function returns the type of SPECIFIER. The returned value
5642 will be a symbol: one of `integer', `boolean', etc., as listed in
5645 Functions are also provided to query whether an object is a
5646 particular kind of specifier:
5648 -- Function: boolean-specifier-p object
5649 This function returns non-`nil' if OBJECT is a boolean specifier.
5651 -- Function: integer-specifier-p object
5652 This function returns non-`nil' if OBJECT is an integer specifier.
5654 -- Function: natnum-specifier-p object
5655 This function returns non-`nil' if OBJECT is a natnum specifier.
5657 -- Function: generic-specifier-p object
5658 This function returns non-`nil' if OBJECT is a generic specifier.
5660 -- Function: face-boolean-specifier-p object
5661 This function returns non-`nil' if OBJECT is a face-boolean
5664 -- Function: toolbar-specifier-p object
5665 This function returns non-`nil' if OBJECT is a toolbar specifier.
5667 -- Function: font-specifier-p object
5668 This function returns non-`nil' if OBJECT is a font specifier.
5670 -- Function: color-specifier-p object
5671 This function returns non-`nil' if OBJECT is a color specifier.
5673 -- Function: image-specifier-p object
5674 This function returns non-`nil' if OBJECT is an image specifier.
5677 File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
5679 48.6 Adding specifications to a Specifier
5680 =========================================
5682 -- Function: add-spec-to-specifier specifier instantiator &optional
5683 locale tag-set how-to-add
5684 This function adds a specification to SPECIFIER. The
5685 specification maps from LOCALE (which should be a window, buffer,
5686 frame, device, or the symbol `global', and defaults to `global')
5687 to INSTANTIATOR, whose allowed values depend on the type of the
5688 specifier. Optional argument TAG-SET limits the instantiator to
5689 apply only to the specified tag set, which should be a list of
5690 tags all of which must match the device being instantiated over
5691 (tags are a device type, a device class, or tags defined with
5692 `define-specifier-tag'). Specifying a single symbol for TAG-SET
5693 is equivalent to specifying a one-element list containing that
5694 symbol. Optional argument HOW-TO-ADD specifies what to do if
5695 there are already specifications in the specifier. It should be
5699 Put at the beginning of the current list of instantiators for
5703 Add to the end of the current list of instantiators for
5706 `remove-tag-set-prepend'
5707 This is the default. Remove any existing instantiators whose
5708 tag set is the same as TAG-SET; then put the new instantiator
5709 at the beginning of the current list.
5711 `remove-tag-set-append'
5712 Remove any existing instantiators whose tag set is the same as
5713 TAG-SET; then put the new instantiator at the end of the
5717 Remove all previous instantiators for this locale before
5718 adding the new spec.
5720 `remove-locale-type'
5721 Remove all specifications for all locales of the same type as
5722 LOCALE (this includes LOCALE itself) before adding the new
5726 Remove all specifications from the specifier before adding
5729 `remove-tag-set-prepend' is the default.
5731 You can retrieve the specifications for a particular locale or
5732 locale type with the function `specifier-spec-list' or
5735 -- Function: add-spec-list-to-specifier specifier spec-list &optional
5737 This function adds a "spec-list" (a list of specifications) to
5738 SPECIFIER. The format of a spec-list is
5740 `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
5744 * LOCALE := a window, a buffer, a frame, a device, or `global'
5746 * TAG-SET := an unordered list of zero or more TAGS, each of
5749 * TAG := a device class (*note Consoles and Devices::), a
5750 device type, or a tag defined with `define-specifier-tag'
5752 * INSTANTIATOR := format determined by the type of specifier
5754 The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A
5755 list of inst-pairs is called an "inst-list". The pair `(LOCALE .
5756 INST-LIST)' is called a "specification". A spec-list, then, can
5757 be viewed as a list of specifications.
5759 HOW-TO-ADD specifies how to combine the new specifications with
5760 the existing ones, and has the same semantics as for
5761 `add-spec-to-specifier'.
5763 The higher-level function `set-specifier' is often more convenient
5764 because it allows abbreviations of spec-lists to be used instead
5765 of the heavily nested canonical syntax. However, one should take
5766 great care in using them with specifiers types which can have lists
5767 as instantiators, such as toolbar specifiers and generic
5768 specifiers. In those cases it's probably best to use
5769 `add-spec-to-specifier' or `add-spec-list-to-specifier'.
5771 -- Special Form: let-specifier specifier-list &rest body
5772 This special form temporarily adds specifications to specifiers,
5773 evaluates forms in BODY and restores the specifiers to their
5774 previous states. The specifiers and their temporary
5775 specifications are listed in SPECIFIER-LIST.
5777 The format of SPECIFIER-LIST is
5779 ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
5781 SPECIFIER is the specifier to be temporarily modified. VALUE is
5782 the instantiator to be temporarily added to specifier in LOCALE.
5783 LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
5784 `add-spec-to-specifier'.
5786 This special form is implemented as a macro; the code resulting
5787 from macro expansion will add specifications to specifiers using
5788 `add-spec-to-specifier'. After forms in BODY are evaluated, the
5789 temporary specifications are removed and old specifier spec-lists
5792 LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
5793 `nil'. The value of the last form in BODY is returned.
5795 NOTE: If you want the specifier's instance to change in all
5796 circumstances, use `(selected-window)' as the LOCALE. If LOCALE
5797 is `nil' or omitted, it defaults to `global'.
5799 The following example removes the 3D modeline effect in the
5800 currently selected window for the duration of a second:
5802 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
5805 -- Function: set-specifier specifier value &optional locale tag-set
5807 This function adds some specifications to SPECIFIER. VALUE can be
5808 a single instantiator or tagged instantiator (added as a global
5809 specification), a list of tagged and/or untagged instantiators
5810 (added as a global specification), a cons of a locale and
5811 instantiator or locale and instantiator list, a list of such
5812 conses, or nearly any other reasonable form. More specifically,
5813 VALUE can be anything accepted by `canonicalize-spec-list'
5816 LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
5817 `add-spec-to-specifier'.
5819 Note that `set-specifier' is exactly complementary to
5820 `specifier-specs' except in the case where SPECIFIER has no specs
5821 at all in it but `nil' is a valid instantiator (in that case,
5822 `specifier-specs' will return `nil' (meaning no specs) and
5823 `set-specifier' will interpret the `nil' as meaning "I'm adding a
5824 global instantiator and its value is `nil'"), or in strange cases
5825 where there is an ambiguity between a spec-list and an inst-list,
5826 etc. (The built-in specifier types are designed in such a way as
5827 to avoid any such ambiguities.) For robust code, `set-specifier'
5828 should probably be avoided for specifier types which accept lists
5829 as instantiators (currently toolbar specifiers and generic
5832 If you want to work with spec-lists, you should probably not use
5833 these functions, but should use the lower-level functions
5834 `specifier-spec-list' and `add-spec-list-to-specifier'. These
5835 functions always work with fully-qualified spec-lists; thus, there
5838 -- Function: canonicalize-inst-pair inst-pair specifier-type &optional
5840 This function canonicalizes the given INST-PAIR.
5842 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5845 Canonicalizing means converting to the full form for an inst-pair,
5846 i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator
5847 is given a tag set of `nil' (the empty set), and a single tag is
5848 converted into a tag set consisting only of that tag.
5850 If NOERROR is non-`nil', signal an error if the inst-pair is
5851 invalid; otherwise return `t'.
5853 -- Function: canonicalize-inst-list inst-list specifier-type &optional
5855 This function canonicalizes the given INST-LIST (a list of
5858 SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
5861 Canonicalizing means converting to the full form for an inst-list,
5862 i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a
5863 single inst-pair or any abbreviation thereof or a list of
5864 (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
5866 If NOERROR is non-`nil', signal an error if the inst-list is
5867 invalid; otherwise return `t'.
5869 -- Function: canonicalize-spec spec specifier-type &optional noerror
5870 This function canonicalizes the given SPEC (a specification).
5872 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5875 Canonicalizing means converting to the full form for a spec, i.e.
5876 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a
5877 possibly abbreviated inst-list or a cons of a locale and a
5878 possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
5880 If NOERROR is `nil', signal an error if the specification is
5881 invalid; otherwise return `t'.
5883 -- Function: canonicalize-spec-list spec-list specifier-type &optional
5885 This function canonicalizes the given SPEC-LIST (a list of
5888 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
5891 If NOERROR is `nil', signal an error if the spec-list is invalid;
5892 otherwise return `t' for an invalid spec-list. (Note that this
5893 cannot be confused with a canonical spec-list.)
5895 Canonicalizing means converting to the full form for a spec-list,
5896 i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This
5897 function accepts a possibly abbreviated specification or a list of
5898 such things. (See `canonicalize-spec'.) This is the function used
5899 to convert spec-lists accepted by `set-specifier' and such into a
5900 form suitable for `add-spec-list-to-specifier'.
5902 This function tries extremely hard to resolve any ambiguities, and
5903 the built-in specifier types (font, image, toolbar, etc.) are
5904 designed so that there won't be any ambiguities.
5906 The canonicalization algorithm is as follows:
5908 1. Attempt to parse SPEC-LIST as a single, possibly abbreviated,
5911 2. If that fails, attempt to parse SPEC-LIST as a list of
5912 (abbreviated) specifications.
5914 3. If that fails, SPEC-LIST is invalid.
5916 A possibly abbreviated specification SPEC is parsed by
5918 1. Attempt to parse SPEC as a possibly abbreviated inst-list.
5920 2. If that fails, attempt to parse SPEC as a cons of a locale
5921 and an (abbreviated) inst-list.
5923 3. If that fails, SPEC is invalid.
5925 A possibly abbreviated inst-list INST-LIST is parsed by
5927 1. Attempt to parse INST-LIST as a possibly abbreviated
5930 2. If that fails, attempt to parse INST-LIST as a list of
5931 (abbreviated) inst-pairs.
5933 3. If that fails, INST-LIST is invalid.
5935 A possibly abbreviated inst-pair INST-PAIR is parsed by
5937 1. Check if INST-PAIR is `valid-instantiator-p'.
5939 2. If not, check if INST-PAIR is a cons of something that is a
5940 tag, ie, `valid-specifier-tag-p', and something that is
5941 `valid-instantiator-p'.
5943 3. If not, check if INST-PAIR is a cons of a list of tags and
5944 something that is `valid-instantiator-p'.
5946 4. Otherwise, INST-PAIR is invalid.
5948 In summary, this function generally prefers more abbreviated forms.
5951 File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
5953 48.7 Retrieving the Specifications from a Specifier
5954 ===================================================
5956 -- Function: specifier-spec-list specifier &optional locale tag-set
5958 This function returns the spec-list of specifications for
5959 SPECIFIER in LOCALE.
5961 If LOCALE is a particular locale (a window, buffer, frame, device,
5962 or the symbol `global'), a spec-list consisting of the
5963 specification for that locale will be returned.
5965 If LOCALE is a locale type (i.e. one of the symbols `window',
5966 `buffer', `frame', or `device'), a spec-list of the specifications
5967 for all locales of that type will be returned.
5969 If LOCALE is `nil' or the symbol `all', a spec-list of all
5970 specifications in SPECIFIER will be returned.
5972 LOCALE can also be a list of locales, locale types, and/or `all';
5973 the result is as if `specifier-spec-list' were called on each
5974 element of the list and the results concatenated together.
5976 Only instantiators where TAG-SET (a list of zero or more tags) is
5977 a subset of (or possibly equal to) the instantiator's tag set are
5978 returned. (The default value of `nil' is a subset of all tag sets,
5979 so in this case no instantiators will be screened out.) If EXACT-P
5980 is non-`nil', however, TAG-SET must be equal to an instantiator's
5981 tag set for the instantiator to be returned.
5983 -- Function: specifier-specs specifier &optional locale tag-set exact-p
5984 This function returns the specification(s) for SPECIFIER in LOCALE.
5986 If LOCALE is a single locale or is a list of one element
5987 containing a single locale, then a "short form" of the
5988 instantiators for that locale will be returned. Otherwise, this
5989 function is identical to `specifier-spec-list'.
5991 The "short form" is designed for readability and not for ease of
5992 use in Lisp programs, and is as follows:
5994 1. If there is only one instantiator, then an inst-pair (i.e.
5995 cons of tag and instantiator) will be returned; otherwise a
5996 list of inst-pairs will be returned.
5998 2. For each inst-pair returned, if the instantiator's tag is
5999 `any', the tag will be removed and the instantiator itself
6000 will be returned instead of the inst-pair.
6002 3. If there is only one instantiator, its value is `nil', and
6003 its tag is `any', a one-element list containing `nil' will be
6004 returned rather than just `nil', to distinguish this case
6005 from there being no instantiators at all.
6008 -- Function: specifier-fallback specifier
6009 This function returns the fallback value for SPECIFIER. Fallback
6010 values are provided by the C code for certain built-in specifiers
6011 to make sure that instancing won't fail even if all specs are
6012 removed from the specifier, or to implement simple inheritance
6013 behavior (e.g. this method is used to ensure that faces other than
6014 `default' inherit their attributes from `default'). By design,
6015 you cannot change the fallback value, and specifiers created with
6016 `make-specifier' will never have a fallback (although a similar,
6017 Lisp-accessible capability may be provided in the future to allow
6020 The fallback value will be an inst-list that is instanced like any
6021 other inst-list, a specifier of the same type as SPECIFIER
6022 (results in inheritance), or `nil' for no fallback.
6024 When you instance a specifier, you can explicitly request that the
6025 fallback not be consulted. (The C code does this, for example, when
6026 merging faces.) See `specifier-instance'.
6029 File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
6031 48.8 Working With Specifier Tags
6032 ================================
6034 A specifier tag set is an entity that is attached to an instantiator
6035 and can be used to restrict the scope of that instantiator to a
6036 particular device class or device type and/or to mark instantiators
6037 added by a particular package so that they can be later removed.
6039 A specifier tag set consists of a list of zero or more specifier
6040 tags, each of which is a symbol that is recognized by XEmacs as a tag.
6041 (The valid device types and device classes are always tags, as are any
6042 tags defined by `define-specifier-tag'.) It is called a "tag set" (as
6043 opposed to a list) because the order of the tags or the number of times
6044 a particular tag occurs does not matter.
6046 Each tag has a predicate associated with it, which specifies whether
6047 that tag applies to a particular device. The tags which are device
6048 types and classes match devices of that type or class. User-defined
6049 tags can have any predicate, or none (meaning that all devices match).
6050 When attempting to instance a specifier, a particular instantiator is
6051 only considered if the device of the domain being instanced over matches
6052 all tags in the tag set attached to that instantiator.
6054 Most of the time, a tag set is not specified, and the instantiator
6055 gets a null tag set, which matches all devices.
6057 -- Function: valid-specifier-tag-p tag
6058 This function returns non-`nil' if TAG is a valid specifier tag.
6060 -- Function: valid-specifier-tag-set-p tag-set
6061 This function returns non-`nil' if TAG-SET is a valid specifier
6064 -- Function: canonicalize-tag-set tag-set
6065 This function canonicalizes the given tag set. Two canonicalized
6066 tag sets can be compared with `equal' to see if they represent the
6067 same tag set. (Specifically, canonicalizing involves sorting by
6068 symbol name and removing duplicates.)
6070 -- Function: device-matches-specifier-tag-set-p device tag-set
6071 This function returns non-`nil' if DEVICE matches specifier tag
6072 set TAG-SET. This means that DEVICE matches each tag in the tag
6075 -- Function: define-specifier-tag tag &optional predicate
6076 This function defines a new specifier tag. If PREDICATE is
6077 specified, it should be a function of one argument (a device) that
6078 specifies whether the tag matches that particular device. If
6079 PREDICATE is omitted, the tag matches all devices.
6081 You can redefine an existing user-defined specifier tag. However,
6082 you cannot redefine the built-in specifier tags (the device types
6083 and classes) or the symbols `nil', `t', `all', or `global'.
6085 -- Function: device-matching-specifier-tag-list &optional device
6086 This function returns a list of all specifier tags matching
6087 DEVICE. DEVICE defaults to the selected device if omitted.
6089 -- Function: specifier-tag-list
6090 This function returns a list of all currently-defined specifier
6091 tags. This includes the built-in ones (the device types and
6094 -- Function: specifier-tag-predicate tag
6095 This function returns the predicate for the given specifier tag.
6098 File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Examples, Prev: Specifier Tag Functions, Up: Specifiers
6100 48.9 Functions for Instancing a Specifier
6101 =========================================
6103 -- Function: specifier-instance specifier &optional domain default
6105 This function instantiates SPECIFIER (returns its value) in
6106 DOMAIN. If no instance can be generated for this domain, return
6109 DOMAIN should be a window, frame, or device. Other values that
6110 are legal as a locale (e.g. a buffer) are not valid as a domain
6111 because they do not provide enough information to identify a
6112 particular device (see `valid-specifier-domain-p'). DOMAIN
6113 defaults to the selected window if omitted.
6115 "Instantiating" a specifier in a particular domain means
6116 determining the specifier's "value" in that domain. This is
6117 accomplished by searching through the specifications in the
6118 specifier that correspond to all locales that can be derived from
6119 the given domain, from specific to general. In most cases, the
6120 domain is an Emacs window. In that case specifications are
6121 searched for as follows:
6123 1. A specification whose locale is the window itself;
6125 2. A specification whose locale is the window's buffer;
6127 3. A specification whose locale is the window's frame;
6129 4. A specification whose locale is the window's frame's device;
6131 5. A specification whose locale is the symbol `global'.
6133 If all of those fail, then the C-code-provided fallback value for
6134 this specifier is consulted (see `specifier-fallback'). If it is
6135 an inst-list, then this function attempts to instantiate that list
6136 just as when a specification is located in the first five steps
6137 above. If the fallback is a specifier, `specifier-instance' is
6138 called recursively on this specifier and the return value used.
6139 Note, however, that if the optional argument NO-FALLBACK is
6140 non-`nil', the fallback value will not be consulted.
6142 Note that there may be more than one specification matching a
6143 particular locale; all such specifications are considered before
6144 looking for any specifications for more general locales. Any
6145 particular specification that is found may be rejected because it
6146 is tagged to a particular device class (e.g. `color') or device
6147 type (e.g. `x') or both and the device for the given domain does
6148 not match this, or because the specification is not valid for the
6149 device of the given domain (e.g. the font or color name does not
6150 exist for this particular X server).
6152 The returned value is dependent on the type of specifier. For
6153 example, for a font specifier (as returned by the `face-font'
6154 function), the returned value will be a font-instance object. For
6155 images, the returned value will be a string, pixmap, or subwindow.
6157 -- Function: specifier-matching-instance specifier matchspec &optional
6158 domain default no-fallback
6159 This function returns an instance for SPECIFIER in DOMAIN that
6160 matches MATCHSPEC. If no instance can be generated for DOMAIN,
6163 This function is identical to `specifier-instance' except that a
6164 specification will only be considered if it matches MATCHSPEC.
6165 The definition of "match," and allowed values for MATCHSPEC, are
6166 dependent on the particular type of specifier. Here are some
6169 * For chartable (e.g. display table) specifiers, MATCHSPEC
6170 should be a character, and the specification (a chartable)
6171 must give a value for that character in order to be
6172 considered. This allows you to specify, _e.g._, a
6173 buffer-local display table that only gives values for
6174 particular characters. All other characters are handled as
6175 if the buffer-local display table is not there. (Chartable
6176 specifiers are not yet implemented.)
6178 * For font specifiers, MATCHSPEC should be a charset, and the
6179 specification (a font string) must have a registry that
6180 matches the charset's registry. (This only makes sense with
6181 Mule support.) This makes it easy to choose a font that can
6182 display a particular character. (This is what redisplay
6185 -- Function: specifier-instance-from-inst-list specifier domain
6186 inst-list &optional default
6187 This function attempts to convert a particular inst-list into an
6188 instance. This attempts to instantiate INST-LIST in the given
6189 DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
6190 If the instantiation fails, DEFAULT is returned. In most
6191 circumstances, you should not use this function; use
6192 `specifier-instance' instead.
6195 File: lispref.info, Node: Specifier Examples, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
6197 48.10 Examples of Specifier Usage
6198 =================================
6200 Now let us present an example to clarify the theoretical discussions we
6201 have been through. In this example, we will use the general specifier
6202 functions for clarity. Keep in mind that many types of specifiers, and
6203 some other types of objects that are associated with specifiers (e.g.
6204 faces), provide convenience functions making it easier to work with
6205 objects of that type.
6207 Let us consider the background color of the default face. A
6208 specifier is used to specify how that color will appear in different
6209 domains. First, let's retrieve the specifier:
6211 (setq sp (face-property 'default 'background))
6212 => #<color-specifier 0x3da>
6214 (specifier-specs sp)
6215 => ((#<buffer "device.c"> (nil . "forest green"))
6216 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
6217 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
6219 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
6220 (global ((tty) . "cyan") (nil . "white"))
6223 Then, say we want to determine what the background color of the
6224 default face is for the window currently displaying the buffer
6225 `*scratch*'. We call
6227 (get-buffer-window "*scratch*")
6228 => #<window on "*scratch*" 0x4ad>
6229 (window-frame (get-buffer-window "*scratch*"))
6230 => #<x-frame "emacs" 0x4ac>
6231 (specifier-instance sp (get-buffer-window "*scratch*"))
6232 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
6234 Note that we passed a window to `specifier-instance', not a buffer.
6235 We cannot pass a buffer because a buffer by itself does not provide
6236 enough information. The buffer might not be displayed anywhere at all,
6237 or could be displayed in many different frames on different devices.
6239 The result is arrived at like this:
6241 1. First, we look for a specification matching the buffer displayed
6242 in the window, i.e. `*scratch*'. There are none, so we proceed.
6244 2. Then, we look for a specification matching the window itself.
6245 Again, there are none.
6247 3. Then, we look for a specification matching the window's frame. The
6248 specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
6249 found. We call the instantiation method for colors, passing it the
6250 locale we were searching over (i.e. the window, in this case) and
6251 the instantiator (`"puke orange"'). However, the particular device
6252 which this window is on (let's say it's an X connection) doesn't
6253 recognize the color `"puke orange"', so the specification is
6256 4. So we continue looking for a specification matching the window's
6257 frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
6258 we call the instantiation method for colors. This time, the X
6259 server our window is on recognizes the color `moccasin', and so the
6260 instantiation method succeeds and returns a color instance.
6262 Here's another example, which implements something like GNU Emacs's
6263 "frame-local" variables.
6267 ;; There are probably better ways to write this macro
6268 ;; Heaven help you if VAR is a buffer-local; you will become very
6269 ;; confused. Probably should error on that.
6270 (defmacro define-frame-local-variable (var)
6271 "Make the unbound symbol VAR become a frame-local variable."
6272 (let ((val (if (boundp var) (symbol-value var) nil)))
6274 (setq ,var (make-specifier 'generic))
6275 (add-spec-to-specifier ,var ',val 'global))))
6277 ;; I'm not real happy about this terminology, how can `setq' be a defun?
6278 ;; But `frame-set' would have people writing "(frame-set 'foo value)".
6279 (defun frame-setq (var value &optional frame)
6280 "Set the local value of VAR to VALUE in FRAME.
6282 FRAME defaults to the selected frame."
6283 (and frame (not (framep frame))
6284 (error 'invalid-argument "FRAME must be a frame", frame))
6285 (add-spec-to-specifier var value (or frame (selected-frame))))
6287 (defun frame-value (var &optional frame)
6288 "Get the local value of VAR in FRAME.
6290 FRAME defaults to the selected frame."
6291 (and frame (not (framep frame))
6292 (error 'invalid-argument "FRAME must be a frame", frame))
6293 ;; this is not just a map from frames to values; it also falls back
6294 ;; to the global value
6295 (specifier-instance var (or frame (selected-frame))))
6298 (defun frame-set-default (var value)
6299 "Set the default value of frame-local variable VAR to VALUE."
6300 (add-spec-to-specifier var value 'global))
6302 (defun frame-get-default (var)
6303 "Get the default value of frame-local variable VAR."
6304 (car (specifier-specs var 'global)))
6306 Now you can execute the above definitions (eg, with `eval-last-sexp')
6307 and switch to `*scratch*' to play. Things will work differently if you
6308 already have a variable named `foo'.
6313 error--> Symbol's value as variable is void: foo
6315 (define-frame-local-variable foo)
6318 ;; the value of foo is a specifier, which is an opaque object;
6319 ;; you must use accessor functions to get values
6322 => #<generic-specifier global=(nil) 0x4f5cb>
6324 ;; since no frame-local value is set, the global value (which is the
6325 ;; constant `nil') is returned
6329 ;; get the default explicitly
6330 (frame-get-default foo)
6333 ;; get the whole specification list
6334 (specifier-specs foo 'global)
6337 ;; give foo a frame-local value
6339 (frame-setq foo 'bar)
6342 ;; access foo in several ways
6344 ;; Note that the print function for this kind of specifier only
6345 ;; gives you the global setting. To get the full list of specs for
6346 ;; debugging or study purposes, you must use specifier-specs or
6347 ;; specifier-spec-list.
6349 => #<generic-specifier global=(nil) 0x4f5cb>
6351 ;; get the whole specification list
6352 (specifier-specs foo)
6353 => ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))
6355 ;; get the frame-local value
6359 ;; get the default explicitly
6360 (frame-get-default foo)
6363 ;; Switch to another frame and evaluate:
6364 ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
6369 (specifier-specs foo)
6370 => ((#<x-frame "emacs" 0x28ec> (nil . baz))
6371 (#<x-frame "Message" 0x1bd66> (nil . bar))
6377 (frame-get-default foo)
6380 Note that since specifiers generalize both frame-local and
6381 buffer-local variables in a sensible way, XEmacs is not likely to put a
6382 high priority on implementing frame-local variables. In fact, some
6383 developers think that frame-local variables are evil for the same
6384 reason that buffer-local variables are evil: the declaration is both
6385 global and invisible. That is, you cannot tell whether a variable is
6386 "normal," buffer-local, or frame-local just by looking at it. So if
6387 you have namespace management problems, and some other Lisp package
6388 happens to use a variable name that you already declared frame- or
6389 buffer-local, weird stuff happens, and it is extremely hard to track
6393 File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Examples, Up: Specifiers
6395 48.11 Creating New Specifier Objects
6396 ====================================
6398 -- Function: make-specifier type
6399 This function creates a new specifier.
6401 A specifier is an object that can be used to keep track of a
6402 property whose value can be per-buffer, per-window, per-frame, or
6403 per-device, and can further be restricted to a particular
6404 device-type or device-class. Specifiers are used, for example,
6405 for the various built-in properties of a face; this allows a face
6406 to have different values in different frames, buffers, etc. For
6407 more information, see `specifier-instance', `specifier-specs', and
6408 `add-spec-to-specifier'; or, for a detailed description of
6409 specifiers, including how they are instantiated over a particular
6410 domain (i.e. how their value in that domain is determined), see
6411 the chapter on specifiers in the XEmacs Lisp Reference Manual.
6413 TYPE specifies the particular type of specifier, and should be one
6414 of the symbols `generic', `integer', `natnum', `boolean', `color',
6415 `font', `image', `face-boolean', or `toolbar'.
6417 For more information on particular types of specifiers, see the
6418 functions `make-generic-specifier', `make-integer-specifier',
6419 `make-natnum-specifier', `make-boolean-specifier',
6420 `make-color-specifier', `make-font-specifier',
6421 `make-image-specifier', `make-face-boolean-specifier', and
6422 `make-toolbar-specifier'.
6424 -- Function: make-specifier-and-init type spec-list &optional
6426 This function creates and initializes a new specifier.
6428 This is a convenience API combining `make-specifier' and
6429 `set-specifier' that allows you to create a specifier and add
6430 specs to it at the same time. TYPE specifies the specifier type.
6431 Allowed types are as for `make-specifier'.
6433 SPEC-LIST supplies the specification(s) to be added to the
6434 specifier. Any abbreviation of the full spec-list form accepted
6435 by `canonicalize-spec-list' may be used. However, if the optional
6436 argument DONT-CANONICALIZE is non-`nil', canonicalization is not
6437 performed, and the SPEC-LIST must already be in full form.
6439 -- Function: make-integer-specifier spec-list
6440 Return a new `integer' specifier object with the given
6441 specification list. SPEC-LIST can be a list of specifications
6442 (each of which is a cons of a locale and a list of instantiators),
6443 a single instantiator, or a list of instantiators.
6445 Valid instantiators for integer specifiers are integers.
6447 -- Function: make-boolean-specifier spec-list
6448 Return a new `boolean' specifier object with the given
6449 specification list. SPEC-LIST can be a list of specifications
6450 (each of which is a cons of a locale and a list of instantiators),
6451 a single instantiator, or a list of instantiators.
6453 Valid instantiators for boolean specifiers are `t' and `nil'.
6455 -- Function: make-natnum-specifier spec-list
6456 Return a new `natnum' specifier object with the given specification
6457 list. SPEC-LIST can be a list of specifications (each of which is
6458 a cons of a locale and a list of instantiators), a single
6459 instantiator, or a list of instantiators.
6461 Valid instantiators for natnum specifiers are non-negative
6464 -- Function: make-generic-specifier spec-list
6465 Return a new `generic' specifier object with the given
6466 specification list. SPEC-LIST can be a list of specifications
6467 (each of which is a cons of a locale and a list of instantiators),
6468 a single instantiator, or a list of instantiators.
6470 Valid instantiators for generic specifiers are all Lisp values.
6471 They are returned back unchanged when a specifier is instantiated.
6473 -- Function: make-display-table-specifier spec-list
6474 Return a new `display-table' specifier object with the given spec
6475 list. SPEC-LIST can be a list of specifications (each of which is
6476 a cons of a locale and a list of instantiators), a single
6477 instantiator, or a list of instantiators.
6479 Valid instantiators for display-table specifiers are described in
6480 detail in the doc string for `current-display-table' (*note Active
6484 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
6486 48.12 Functions for Checking the Validity of Specifier Components
6487 =================================================================
6489 -- Function: valid-specifier-domain-p domain
6490 This function returns non-`nil' if DOMAIN is a valid specifier
6491 domain. A domain is used to instance a specifier (i.e. determine
6492 the specifier's value in that domain). Valid domains are a
6493 window, frame, or device. (`nil' is not valid.)
6495 -- Function: valid-specifier-locale-p locale
6496 This function returns non-`nil' if LOCALE is a valid specifier
6497 locale. Valid locales are a device, a frame, a window, a buffer,
6498 and `global'. (`nil' is not valid.)
6500 -- Function: valid-specifier-locale-type-p locale-type
6501 Given a specifier LOCALE-TYPE, this function returns non-`nil' if
6502 it is valid. Valid locale types are the symbols `global',
6503 `device', `frame', `window', and `buffer'. (Note, however, that in
6504 functions that accept either a locale or a locale type, `global'
6505 is considered an individual locale.)
6507 -- Function: valid-specifier-type-p specifier-type
6508 Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
6509 valid. Valid types are `generic', `integer', `boolean', `color',
6510 `font', `image', `face-boolean', and `toolbar'.
6512 -- Function: valid-specifier-tag-p tag
6513 This function returns non-`nil' if TAG is a valid specifier tag.
6515 -- Function: valid-instantiator-p instantiator specifier-type
6516 This function returns non-`nil' if INSTANTIATOR is valid for
6519 -- Function: valid-inst-list-p inst-list type
6520 This function returns non-`nil' if INST-LIST is valid for
6521 specifier type TYPE.
6523 -- Function: valid-spec-list-p spec-list type
6524 This function returns non-`nil' if SPEC-LIST is valid for
6525 specifier type TYPE.
6527 -- Function: check-valid-instantiator instantiator specifier-type
6528 This function signals an error if INSTANTIATOR is invalid for
6531 -- Function: check-valid-inst-list inst-list type
6532 This function signals an error if INST-LIST is invalid for
6533 specifier type TYPE.
6535 -- Function: check-valid-spec-list spec-list type
6536 This function signals an error if SPEC-LIST is invalid for
6537 specifier type TYPE.
6540 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
6542 48.13 Other Functions for Working with Specifications in a Specifier
6543 ====================================================================
6545 -- Function: copy-specifier specifier &optional dest locale tag-set
6547 This function copies SPECIFIER to DEST, or creates a new one if
6550 If DEST is `nil' or omitted, a new specifier will be created and
6551 the specifications copied into it. Otherwise, the specifications
6552 will be copied into the existing specifier in DEST.
6554 If LOCALE is `nil' or the symbol `all', all specifications will be
6555 copied. If LOCALE is a particular locale, the specification for
6556 that particular locale will be copied. If LOCALE is a locale
6557 type, the specifications for all locales of that type will be
6558 copied. LOCALE can also be a list of locales, locale types,
6559 and/or `all'; this is equivalent to calling `copy-specifier' for
6560 each of the elements of the list. See `specifier-spec-list' for
6561 more information about LOCALE.
6563 Only instantiators where TAG-SET (a list of zero or more tags) is
6564 a subset of (or possibly equal to) the instantiator's tag set are
6565 copied. (The default value of `nil' is a subset of all tag sets,
6566 so in this case no instantiators will be screened out.) If EXACT-P
6567 is non-`nil', however, TAG-SET must be equal to an instantiator's
6568 tag set for the instantiator to be copied.
6570 Optional argument HOW-TO-ADD specifies what to do with existing
6571 specifications in DEST. If `nil', then whichever locales or locale
6572 types are copied will first be completely erased in DEST.
6573 Otherwise, it is the same as in `add-spec-to-specifier'.
6575 -- Function: remove-specifier specifier &optional locale tag-set
6577 This function removes specification(s) for SPECIFIER.
6579 If LOCALE is a particular locale (a buffer, window, frame, device,
6580 or the symbol `global'), the specification for that locale will be
6583 If instead, LOCALE is a locale type (i.e. a symbol `buffer',
6584 `window', `frame', or `device'), the specifications for all
6585 locales of that type will be removed.
6587 If LOCALE is `nil' or the symbol `all', all specifications will be
6590 LOCALE can also be a list of locales, locale types, and/or `all';
6591 this is equivalent to calling `remove-specifier' for each of the
6592 elements in the list.
6594 Only instantiators where TAG-SET (a list of zero or more tags) is
6595 a subset of (or possibly equal to) the instantiator's tag set are
6596 removed. (The default value of `nil' is a subset of all tag sets,
6597 so in this case no instantiators will be screened out.) If EXACT-P
6598 is non-`nil', however, TAG-SET must be equal to an instantiator's
6599 tag set for the instantiator to be removed.
6601 -- Function: map-specifier specifier func &optional locale maparg
6602 This function applies FUNC to the specification(s) for LOCALE in
6605 If optional LOCALE is a locale, FUNC will be called for that
6606 locale. If LOCALE is a locale type, FUNC will be mapped over all
6607 locales of that type. If LOCALE is `nil' or the symbol `all',
6608 FUNC will be mapped over all locales in SPECIFIER.
6610 Optional MS-MAPARG will be passed to MS-FUNC.
6612 FUNC is called with four arguments: the SPECIFIER, the locale
6613 being mapped over, the inst-list for that locale, and the optional
6614 MAPARG. If any invocation of FUNC returns non-`nil', the mapping
6615 will stop and the returned value becomes the value returned from
6616 `map-specifier'. Otherwise, `map-specifier' returns `nil'.
6618 -- Function: specifier-locale-type-from-locale locale
6619 Given a specifier LOCALE, this function returns its type.
6622 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
6624 49 Faces and Window-System Objects
6625 **********************************
6629 * Faces:: Controlling the way text looks.
6630 * Fonts:: Controlling the typeface of text.
6631 * Colors:: Controlling the color of text and pixmaps.
6634 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
6639 A "face" is a named collection of graphical properties: font,
6640 foreground color, background color, background pixmap, optional
6641 underlining, and (on TTY devices) whether the text is to be highlighted,
6642 dimmed, blinking, or displayed in reverse video. Faces control the
6643 display of text on the screen. Every face has a name, which is a symbol
6644 such as `default' or `modeline'.
6646 Each built-in property of a face is controlled using a specifier,
6647 which allows it to have separate values in particular buffers, frames,
6648 windows, and devices and to further vary according to device type (X or
6649 TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
6650 for more information.
6652 The face named `default' is used for ordinary text. The face named
6653 `modeline' is used for displaying the modeline. The face named
6654 `highlight' is used for highlighted extents (*note Extents::). The
6655 faces named `left-margin' and `right-margin' are used for the left and
6656 right margin areas, respectively (*note Annotations::). The face named
6657 `zmacs-region' is used for the highlighted region between point and
6662 * Merging Faces:: How XEmacs decides which face to use
6664 * Basic Face Functions:: How to define and examine faces.
6665 * Face Properties:: How to access and modify a face's properties.
6666 * Face Convenience Functions:: Convenience functions for accessing
6667 particular properties of a face.
6668 * Other Face Display Functions:: Other functions pertaining to how a
6672 File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
6674 49.1.1 Merging Faces for Display
6675 --------------------------------
6677 Here are all the ways to specify which face to use for display of text:
6679 * With defaults. Each frame has a "default face", which is used for
6680 all text that doesn't somehow specify another face. The face named
6681 `default' applies to the text area, while the faces `left-margin'
6682 and `right-margin' apply to the left and right margin areas.
6684 * With text properties. A character may have a `face' property; if
6685 so, it's displayed with that face. (Text properties are actually
6686 implemented in terms of extents.) *Note Text Properties::.
6688 * With extents. An extent may have a `face' property, which applies
6689 to all the text covered by the extent; in addition, if the
6690 `highlight' property is set, the `highlight' property applies when
6691 the mouse moves over the extent or if the extent is explicitly
6692 highlighted. *Note Extents::.
6694 * With annotations. Annotations that are inserted into a buffer can
6695 specify their own face. (Annotations are actually implemented in
6696 terms of extents.) *Note Annotations::.
6698 If these various sources together specify more than one face for a
6699 particular character, XEmacs merges the properties of the various faces
6700 specified. Extents, text properties, and annotations all use the same
6701 underlying representation (as extents). When multiple extents cover one
6702 character, an extent with higher priority overrides those with lower
6703 priority. *Note Extents::. If no extent covers a particular character,
6704 the `default' face is used.
6706 If a background pixmap is specified, it determines what will be
6707 displayed in the background of text characters. If the background
6708 pixmap is actually a pixmap, with its colors specified, those colors are
6709 used; if it is a bitmap, the face's foreground and background colors are
6713 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
6715 49.1.2 Basic Functions for Working with Faces
6716 ---------------------------------------------
6718 The properties a face can specify include the font, the foreground
6719 color, the background color, the background pixmap, the underlining,
6720 the display table, and (for TTY devices) whether the text is to be
6721 highlighted, dimmed, blinking, or displayed in reverse video. The face
6722 can also leave these unspecified, causing them to assume the value of
6723 the corresponding property of the `default' face.
6725 Here are the basic primitives for working with faces.
6727 -- Function: make-face name &optional doc-string temporary
6728 This function defines and returns a new face named NAME, initially
6729 with all properties unspecified. It does nothing if there is
6730 already a face named NAME. Optional argument DOC-STRING specifies
6731 an explanatory string used for descriptive purposes. If optional
6732 argument TEMPORARY is non-`nil', the face will automatically
6733 disappear when there are no more references to it anywhere in text
6734 or Lisp code (otherwise, the face will continue to exist
6735 indefinitely even if it is not used).
6737 -- Function: face-list &optional temporary
6738 This function returns a list of the names of all defined faces. If
6739 TEMPORARY is `nil', only the permanent faces are included. If it
6740 is `t', only the temporary faces are included. If it is any other
6741 non-`nil' value both permanent and temporary are included.
6743 -- Function: facep object
6744 This function returns `t' if OBJECT is a face, else `nil'.
6746 -- Function: copy-face old-face new-name &optional locale tag-set
6748 This function defines a new face named NEW-NAME which is a copy of
6749 the existing face named OLD-FACE. If there is already a face
6750 named NEW-NAME, then it alters the face to have the same
6751 properties as OLD-FACE.
6753 LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
6754 the old face rather than the whole face, and are as in
6755 `copy-specifier' (*note Specifiers::).
projects / chise / xemacs-chise.git.1 / blob