This is ../info/lispref.info, produced by makeinfo version 4.6 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text Maintaining Undo Lists ====================== This section describes how to enable and disable undo information for a given buffer. It also explains how the undo list is truncated automatically so it doesn't get too big. Recording of undo information in a newly created buffer is normally enabled to start with; but if the buffer name starts with a space, the undo recording is initially disabled. You can explicitly enable or disable undo recording with the following two functions, or by setting `buffer-undo-list' yourself. - Command: buffer-enable-undo &optional buffer-or-name This command enables recording undo information for buffer BUFFER-OR-NAME, so that subsequent changes can be undone. If no argument is supplied, then the current buffer is used. This function does nothing if undo recording is already enabled in the buffer. It returns `nil'. In an interactive call, BUFFER-OR-NAME is the current buffer. You cannot specify any other buffer. - Command: buffer-disable-undo &optional buffer - Command: buffer-flush-undo &optional buffer This function discards the undo list of BUFFER, and disables further recording of undo information. As a result, it is no longer possible to undo either previous changes or any subsequent changes. If the undo list of BUFFER is already disabled, this function has no effect. This function returns `nil'. It cannot be called interactively. The name `buffer-flush-undo' is not considered obsolete, but the preferred name `buffer-disable-undo' is new as of Emacs versions 19. As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims them back to size limits you can set. (For this purpose, the "size" of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Two variables control the range of acceptable sizes: `undo-limit' and `undo-strong-limit'. - Variable: undo-limit This is the soft limit for the acceptable size of an undo list. The change group at which this size is exceeded is the last one kept. - Variable: undo-strong-limit This is the upper limit for the acceptable size of an undo list. The change group at which this size is exceeded is discarded itself (along with all older change groups). There is one exception: the very latest change group is never discarded no matter how big it is.  File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text Filling ======= "Filling" means adjusting the lengths of lines (by moving the line breaks) so that they are nearly (but no greater than) a specified maximum width. Additionally, lines can be "justified", which means inserting spaces to make the left and/or right margins line up precisely. The width is controlled by the variable `fill-column'. For ease of reading, lines should be no longer than 70 or so columns. You can use Auto Fill mode (*note Auto Filling::) to fill text automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly. Most of the commands in this section return values that are not meaningful. All the functions that do filling take note of the current left margin, current right margin, and current justification style (*note Margins::). If the current justification style is `none', the filling functions don't actually do anything. Several of the filling functions have an argument JUSTIFY. If it is non-`nil', that requests some kind of justification. It can be `left', `right', `full', or `center', to request a specific style of justification. If it is `t', that means to use the current justification style for this part of the text (see `current-justification', below). When you call the filling functions interactively, using a prefix argument implies the value `full' for JUSTIFY. - Command: fill-paragraph justify This command fills the paragraph at or after point. If JUSTIFY is non-`nil', each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. *Note Paragraphs: (xemacs)Paragraphs. - Command: fill-region start end &optional justify This command fills each of the paragraphs in the region from START to END. It justifies as well if JUSTIFY is non-`nil'. The variable `paragraph-separate' controls how to distinguish paragraphs. *Note Standard Regexps::. - Command: fill-individual-paragraphs start end &optional justify mail-flag This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented with spaces, the filled paragraph will remain indented in the same fashion. The first two arguments, START and END, are the beginning and end of the region to be filled. The third and fourth arguments, JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the paragraphs are justified as well as filled. If MAIL-FLAG is non-`nil', it means the function is operating on a mail message and therefore should not fill the header lines. Ordinarily, `fill-individual-paragraphs' regards each change in indentation as starting a new paragraph. If `fill-individual-varying-indent' is non-`nil', then only separator lines separate paragraphs. That mode can handle indented paragraphs with additional indentation on the first line. - User Option: fill-individual-varying-indent This variable alters the action of `fill-individual-paragraphs' as described above. - Command: fill-region-as-paragraph start end &optional justify This command considers a region of text as a paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as filling when JUSTIFY is non-`nil'. In an interactive call, any prefix argument requests justification. In Adaptive Fill mode, which is enabled by default, `fill-region-as-paragraph' on an indented paragraph when there is no fill prefix uses the indentation of the second line of the paragraph as the fill prefix. - Command: justify-current-line how eop nosqueeze This command inserts spaces between the words of the current line so that the line ends exactly at `fill-column'. It returns `nil'. The argument HOW, if non-`nil' specifies explicitly the style of justification. It can be `left', `right', `full', `center', or `none'. If it is `t', that means to do follow specified justification style (see `current-justification', below). `nil' means to do full justification. If EOP is non-`nil', that means do left-justification when `current-justification' specifies full justification. This is used for the last line of a paragraph; even if the paragraph as a whole is fully justified, the last line should not be. If NOSQUEEZE is non-`nil', that means do not change interior whitespace. - User Option: default-justification This variable's value specifies the style of justification to use for text that doesn't specify a style with a text property. The possible values are `left', `right', `full', `center', or `none'. The default value is `left'. - Function: current-justification This function returns the proper justification style to use for filling the text around point. - Variable: fill-paragraph-function This variable provides a way for major modes to override the filling of paragraphs. If the value is non-`nil', `fill-paragraph' calls this function to do the work. If the function returns a non-`nil' value, `fill-paragraph' assumes the job is done, and immediately returns that value. The usual use of this feature is to fill comments in programming language modes. If the function needs to fill a paragraph in the usual way, it can do so as follows: (let ((fill-paragraph-function nil)) (fill-paragraph arg)) - Variable: use-hard-newlines If this variable is non-`nil', the filling functions do not delete newlines that have the `hard' text property. These "hard newlines" act as paragraph separators.  File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text Margins for Filling =================== - User Option: fill-prefix This variable specifies a string of text that appears at the beginning of normal text lines and should be disregarded when filling them. Any line that fails to start with the fill prefix is considered the start of a paragraph; so is any line that starts with the fill prefix followed by additional whitespace. Lines that start with the fill prefix but no additional whitespace are ordinary text lines that can be filled together. The resulting filled lines also start with the fill prefix. The fill prefix follows the left margin whitespace, if any. - User Option: fill-column This buffer-local variable specifies the maximum width of filled lines. Its value should be an integer, which is a number of columns. All the filling, justification and centering commands are affected by this variable, including Auto Fill mode (*note Auto Filling::). As a practical matter, if you are writing text for other people to read, you should set `fill-column' to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy. - Variable: default-fill-column The value of this variable is the default value for `fill-column' in buffers that do not override it. This is the same as `(default-value 'fill-column)'. The default value for `default-fill-column' is 70. - Command: set-left-margin from to margin This sets the `left-margin' property on the text from FROM to TO to the value MARGIN. If Auto Fill mode is enabled, this command also refills the region to fit the new margin. - Command: set-right-margin from to margin This sets the `right-margin' property on the text from FROM to TO to the value MARGIN. If Auto Fill mode is enabled, this command also refills the region to fit the new margin. - Function: current-left-margin This function returns the proper left margin value to use for filling the text around point. The value is the sum of the `left-margin' property of the character at the start of the current line (or zero if none), and the value of the variable `left-margin'. - Function: current-fill-column This function returns the proper fill column value to use for filling the text around point. The value is the value of the `fill-column' variable, minus the value of the `right-margin' property of the character after point. - Command: move-to-left-margin &optional n force This function moves point to the left margin of the current line. The column moved to is determined by calling the function `current-left-margin'. If the argument N is non-`nil', `move-to-left-margin' moves forward N-1 lines first. If FORCE is non-`nil', that says to fix the line's indentation if that doesn't match the left margin value. - Function: delete-to-left-margin &optional from to This function removes left margin indentation from the text between FROM and TO. The amount of indentation to delete is determined by calling `current-left-margin'. In no case does this function delete non-whitespace. The arguments FROM and TO are optional; the default is the whole buffer. - Function: indent-to-left-margin This is the default `indent-line-function', used in Fundamental mode, Text mode, etc. Its effect is to adjust the indentation at the beginning of the current line to the value specified by the variable `left-margin'. This may involve either inserting or deleting whitespace. - Variable: left-margin This variable specifies the base left margin column. In Fundamental mode, indents to this column. This variable automatically becomes buffer-local when set in any fashion.  File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text Auto Filling ============ Auto Fill mode is a minor mode that fills lines automatically as text is inserted. This section describes the hook used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see *Note Filling::. Auto Fill mode also enables the functions that change the margins and justification style to refill portions of the text. *Note Margins::. - Variable: auto-fill-function The value of this variable should be a function (of no arguments) to be called after self-inserting a space or a newline. It may be `nil', in which case nothing special is done in that case. The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill mode is enabled. That is a function whose sole purpose is to implement the usual strategy for breaking a line. In older Emacs versions, this variable was named `auto-fill-hook', but since it is not called with the standard convention for hooks, it was renamed to `auto-fill-function' in version 19.  File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text Sorting Text ============ The sorting functions described in this section all rearrange text in a buffer. This is in contrast to the function `sort', which rearranges the order of the elements of a list (*note Rearrangement::). The values returned by these functions are not meaningful. - Function: sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun This function is the general text-sorting routine that divides a buffer into records and sorts them. Most of the commands in this section use this function. To understand how `sort-subr' works, consider the whole accessible portion of the buffer as being divided into disjoint pieces called "sort records". The records may or may not be contiguous; they may not overlap. A portion of each sort record (perhaps all of it) is designated as the sort key. Sorting rearranges the records in order by their sort keys. Usually, the records are rearranged in order of ascending sort key. If the first argument to the `sort-subr' function, REVERSE, is non-`nil', the sort records are rearranged in order of descending sort key. The next four arguments to `sort-subr' are functions that are called to move point across a sort record. They are called many times from within `sort-subr'. 1. NEXTRECFUN is called with point at the end of a record. This function moves point to the start of the next record. The first record is assumed to start at the position of point when `sort-subr' is called. Therefore, you should usually move point to the beginning of the buffer before calling `sort-subr'. This function can indicate there are no more sort records by leaving point at the end of the buffer. 2. ENDRECFUN is called with point within a record. It moves point to the end of the record. 3. STARTKEYFUN is called to move point from the start of a record to the start of the sort key. This argument is optional; if it is omitted, the whole record is the sort key. If supplied, the function should either return a non-`nil' value to be used as the sort key, or return `nil' to indicate that the sort key is in the buffer starting at point. In the latter case, ENDKEYFUN is called to find the end of the sort key. 4. ENDKEYFUN is called to move point from the start of the sort key to the end of the sort key. This argument is optional. If STARTKEYFUN returns `nil' and this argument is omitted (or `nil'), then the sort key extends to the end of the record. There is no need for ENDKEYFUN if STARTKEYFUN returns a non-`nil' value. As an example of `sort-subr', here is the complete function definition for `sort-lines': ;; Note that the first two lines of doc string ;; are effectively one line when viewed by a user. (defun sort-lines (reverse start end) "Sort lines in region alphabetically. Called from a program, there are three arguments: REVERSE (non-nil means reverse order), and START and END (the region to sort)." (interactive "P\nr") (save-restriction (narrow-to-region start end) (goto-char (point-min)) (sort-subr reverse 'forward-line 'end-of-line))) Here `forward-line' moves point to the start of the next record, and `end-of-line' moves point to the end of record. We do not pass the arguments STARTKEYFUN and ENDKEYFUN, because the entire record is used as the sort key. The `sort-paragraphs' function is very much the same, except that its `sort-subr' call looks like this: (sort-subr reverse (function (lambda () (skip-chars-forward "\n \t\f"))) 'forward-paragraph) - Command: sort-regexp-fields reverse record-regexp key-regexp start end This command sorts the region between START and END alphabetically as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a negative integer, then sorting is in reverse order. Alphabetical sorting means that two sort keys are compared by comparing the first characters of each, the second characters of each, and so on. If a mismatch is found, it means that the sort keys are unequal; the sort key whose character is less at the point of first mismatch is the lesser sort key. The individual characters are compared according to their numerical values. Since Emacs uses the ASCII character set, the ordering in that set determines alphabetical order. The value of the RECORD-REGEXP argument specifies how to divide the buffer into sort records. At the end of each record, a search is done for this regular expression, and the text that matches it is the next record. For example, the regular expression `^.+$', which matches lines with at least one character besides a newline, would make each such line into a sort record. *Note Regular Expressions::, for a description of the syntax and meaning of regular expressions. The value of the KEY-REGEXP argument specifies what part of each record is the sort key. The KEY-REGEXP could match the whole record, or only a part. In the latter case, the rest of the record has no effect on the sorted order of records, but it is carried along when the record moves to its new position. The KEY-REGEXP argument can refer to the text matched by a subexpression of RECORD-REGEXP, or it can be a regular expression on its own. If KEY-REGEXP is: `\DIGIT' then the text matched by the DIGITth `\(...\)' parenthesis grouping in RECORD-REGEXP is the sort key. `\&' then the whole record is the sort key. a regular expression then `sort-regexp-fields' searches for a match for the regular expression within the record. If such a match is found, it is the sort key. If there is no match for KEY-REGEXP within a record then that record is ignored, which means its position in the buffer is not changed. (The other records may move around it.) For example, if you plan to sort all the lines in the region by the first word on each line starting with the letter `f', you should set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\'. The resulting expression looks like this: (sort-regexp-fields nil "^.*$" "\\" (region-beginning) (region-end)) If you call `sort-regexp-fields' interactively, it prompts for RECORD-REGEXP and KEY-REGEXP in the minibuffer. - Command: sort-lines reverse start end This command alphabetically sorts lines in the region between START and END. If REVERSE is non-`nil', the sort is in reverse order. - Command: sort-paragraphs reverse start end This command alphabetically sorts paragraphs in the region between START and END. If REVERSE is non-`nil', the sort is in reverse order. - Command: sort-pages reverse start end This command alphabetically sorts pages in the region between START and END. If REVERSE is non-`nil', the sort is in reverse order. - Command: sort-fields field start end This command sorts lines in the region between START and END, comparing them alphabetically by the FIELDth field of each line. Fields are separated by whitespace and numbered starting from 1. If FIELD is negative, sorting is by the -FIELDth field from the end of the line. This command is useful for sorting tables. - Command: sort-numeric-fields field start end This command sorts lines in the region between START and END, comparing them numerically by the FIELDth field of each line. The specified field must contain a number in each line of the region. Fields are separated by whitespace and numbered starting from 1. If FIELD is negative, sorting is by the -FIELDth field from the end of the line. This command is useful for sorting tables. - Command: sort-columns reverse &optional start end This command sorts the lines in the region between START and END, comparing them alphabetically by a certain range of columns. The column positions of START and END bound the range of columns to sort on. If REVERSE is non-`nil', the sort is in reverse order. One unusual thing about this command is that the entire line containing position START, and the entire line containing position END, are included in the region sorted. Note that `sort-columns' uses the `sort' utility program, and so cannot work properly on text containing tab characters. Use `M-x `untabify'' to convert tabs to spaces before sorting.  File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text Counting Columns ================ The column functions convert between a character position (counting characters from the beginning of the buffer) and a column position (counting screen characters from the beginning of a line). A character counts according to the number of columns it occupies on the screen. This means control characters count as occupying 2 or 4 columns, depending upon the value of `ctl-arrow', and tabs count as occupying a number of columns that depends on the value of `tab-width' and on the column where the tab begins. *Note Usual Display::. Column number computations ignore the width of the window and the amount of horizontal scrolling. Consequently, a column value can be arbitrarily high. The first (or leftmost) column is numbered 0. - Function: current-column &optional buffer This function returns the horizontal position of point, measured in columns, counting from 0 at the left margin. This is calculated by adding together the widths of all the displayed representations of the character between the start of the previous line and point. (e.g. control characters will have a width of 2 or 4, tabs will have a variable width.) Ignores the finite width of frame displaying the buffer, which means that this function may return values greater than `(frame-width)'. Whether the line is visible (if `selective-display' is t) has no effect; however, ^M is treated as end of line when `selective-display' is t. If BUFFER is nil, the current buffer is assumed. For an example of using `current-column', see the description of `count-lines' in *Note Text Lines::. - Function: move-to-column column &optional force buffer This function moves point to COLUMN in the current line. The calculation of COLUMN takes into account the widths of the displayed representations of the characters between the start of the line and point. If column COLUMN is beyond the end of the line, point moves to the end of the line. If COLUMN is negative, point moves to the beginning of the line. If it is impossible to move to column COLUMN because that is in the middle of a multicolumn character such as a tab, point moves to the end of that character. However, if FORCE is non-`nil', and COLUMN is in the middle of a tab, then `move-to-column' converts the tab into spaces so that it can move precisely to column COLUMN. Other multicolumn characters can cause anomalies despite FORCE, since there is no way to split them. The argument FORCE also has an effect if the line isn't long enough to reach column COLUMN; in that case, unless the value of FORCE is the special value `coerce', it says to add whitespace at the end of the line to reach that column. If COLUMN is not a non-negative integer, an error is signaled. The return value is the column number actually moved to.  File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text Indentation =========== The indentation functions are used to examine, move to, and change whitespace that is at the beginning of a line. Some of the functions can also change whitespace elsewhere on a line. Columns and indentation count from zero at the left margin. * Menu: * Primitive Indent:: Functions used to count and insert indentation. * Mode-Specific Indent:: Customize indentation for different modes. * Region Indent:: Indent all the lines in a region. * Relative Indent:: Indent the current line based on previous lines. * Indent Tabs:: Adjustable, typewriter-like tab stops. * Motion by Indent:: Move to first non-blank character.  File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation Indentation Primitives ---------------------- This section describes the primitive functions used to count and insert indentation. The functions in the following sections use these primitives. - Function: current-indentation &optional buffer This function returns the indentation of the current line, which is the horizontal position of the first nonblank character. If the contents are entirely blank, then this is the horizontal position of the end of the line. - Command: indent-to column &optional minimum buffer This function indents from point with tabs and spaces until COLUMN is reached. If MINIMUM is specified and non-`nil', then at least that many spaces are inserted even if this requires going beyond COLUMN. Otherwise the function does nothing if point is already beyond COLUMN. The value is the column at which the inserted indentation ends. If BUFFER is `nil', the current buffer is assumed. - User Option: indent-tabs-mode If this variable is non-`nil', indentation functions can insert tabs as well as spaces. Otherwise, they insert only spaces. Setting this variable automatically makes it local to the current buffer.  File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation Indentation Controlled by Major Mode ------------------------------------ An important function of each major mode is to customize the key to indent properly for the language being edited. This section describes the mechanism of the key and how to control it. The functions in this section return unpredictable values. - Variable: indent-line-function This variable's value is the function to be used by (and various commands) to indent the current line. The command `indent-according-to-mode' does no more than call this function. In Lisp mode, the value is the symbol `lisp-indent-line'; in C mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In Fundamental mode, Text mode, and many other modes with no standard for indentation, the value is `indent-to-left-margin' (which is the default value). - Command: indent-according-to-mode This command calls the function in `indent-line-function' to indent the current line in a way appropriate for the current major mode. - Command: indent-for-tab-command &optional prefix-arg This command calls the function in `indent-line-function' to indent the current line; except that if that function is `indent-to-left-margin', it calls `insert-tab' instead. (That is a trivial command that inserts a tab character.) - Command: newline-and-indent This function inserts a newline, then indents the new line (the one following the newline just inserted) according to the major mode. It does indentation by calling the current `indent-line-function'. In programming language modes, this is the same thing does, but in some text modes, where inserts a tab, `newline-and-indent' indents to the column specified by `left-margin'. - Command: reindent-then-newline-and-indent This command reindents the current line, inserts a newline at point, and then reindents the new line (the one following the newline just inserted). This command does indentation on both lines according to the current major mode, by calling the current value of `indent-line-function'. In programming language modes, this is the same thing does, but in some text modes, where inserts a tab, `reindent-then-newline-and-indent' indents to the column specified by `left-margin'.  File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation Indenting an Entire Region -------------------------- This section describes commands that indent all the lines in the region. They return unpredictable values. - Command: indent-region start end to-column This command indents each nonblank line starting between START (inclusive) and END (exclusive). If TO-COLUMN is `nil', `indent-region' indents each nonblank line by calling the current mode's indentation function, the value of `indent-line-function'. If TO-COLUMN is non-`nil', it should be an integer specifying the number of columns of indentation; then this function gives each line exactly that much indentation, by either adding or deleting whitespace. If there is a fill prefix, `indent-region' indents each line by making it start with the fill prefix. - Variable: indent-region-function The value of this variable is a function that can be used by `indent-region' as a short cut. You should design the function so that it will produce the same results as indenting the lines of the region one by one, but presumably faster. If the value is `nil', there is no short cut, and `indent-region' actually works line by line. A short-cut function is useful in modes such as C mode and Lisp mode, where the `indent-line-function' must scan from the beginning of the function definition: applying it to each line would be quadratic in time. The short cut can update the scan information as it moves through the lines indenting them; this takes linear time. In a mode where indenting a line individually is fast, there is no need for a short cut. `indent-region' with a non-`nil' argument TO-COLUMN has a different meaning and does not use this variable. - Command: indent-rigidly start end count This command indents all lines starting between START (inclusive) and END (exclusive) sideways by COUNT columns. This "preserves the shape" of the affected region, moving it as a rigid unit. Consequently, this command is useful not only for indenting regions of unindented text, but also for indenting regions of formatted code. For example, if COUNT is 3, this command adds 3 columns of indentation to each of the lines beginning in the region specified. In Mail mode, `C-c C-y' (`mail-yank-original') uses `indent-rigidly' to indent the text copied from the message being replied to. - Command: indent-code-rigidly start end columns &optional nochange-regexp This is like `indent-rigidly', except that it doesn't alter lines that start within strings or comments. In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at the beginning of the line (if NOCHANGE-REGEXP is non-`nil').  File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation Indentation Relative to Previous Lines -------------------------------------- This section describes two commands that indent the current line based on the contents of previous lines. - Command: indent-relative &optional unindented-ok This command inserts whitespace at point, extending to the same column as the next "indent point" of the previous nonblank line. An indent point is a non-whitespace character following whitespace. The next indent point is the first one at a column greater than the current column of point. For example, if point is underneath and to the left of the first non-blank character of a line of text, it moves to that column by inserting whitespace. If the previous nonblank line has no next indent point (i.e., none at a great enough column position), `indent-relative' either does nothing (if UNINDENTED-OK is non-`nil') or calls `tab-to-tab-stop'. Thus, if point is underneath and to the right of the last column of a short line of text, this command ordinarily moves point to the next tab stop by inserting whitespace. The return value of `indent-relative' is unpredictable. In the following example, point is at the beginning of the second line: This line is indented twelve spaces. -!-The quick brown fox jumped. Evaluation of the expression `(indent-relative nil)' produces the following: This line is indented twelve spaces. -!-The quick brown fox jumped. In this example, point is between the `m' and `p' of `jumped': This line is indented twelve spaces. The quick brown fox jum-!-ped. Evaluation of the expression `(indent-relative nil)' produces the following: This line is indented twelve spaces. The quick brown fox jum -!-ped. - Command: indent-relative-maybe This command indents the current line like the previous nonblank line. It calls `indent-relative' with `t' as the UNINDENTED-OK argument. The return value is unpredictable. If the previous nonblank line has no indent points beyond the current column, this command does nothing.  File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation Adjustable "Tab Stops" ---------------------- This section explains the mechanism for user-specified "tab stops" and the mechanisms that use and set them. The name "tab stops" is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of spaces and tab characters to reach the next tab stop column; it does not affect the display of tab characters in the buffer (*note Usual Display::). Note that the character as input uses this tab stop feature only in a few major modes, such as Text mode. - Command: tab-to-tab-stop This command inserts spaces or tabs up to the next tab stop column defined by `tab-stop-list'. It searches the list for an element greater than the current column number, and uses that element as the column to indent to. It does nothing if no such element is found. - User Option: tab-stop-list This variable is the list of tab stop columns used by `tab-to-tab-stops'. The elements should be integers in increasing order. The tab stop columns need not be evenly spaced. Use `M-x edit-tab-stops' to edit the location of tab stops interactively.  File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation Indentation-Based Motion Commands --------------------------------- These commands, primarily for interactive use, act based on the indentation in the text. - Command: back-to-indentation This command moves point to the first non-whitespace character in the current line (which is the line in which point is located). It returns `nil'. - Command: backward-to-indentation arg This command moves point backward ARG lines and then to the first nonblank character on that line. It returns `nil'. - Command: forward-to-indentation arg This command moves point forward ARG lines and then to the first nonblank character on that line. It returns `nil'.  File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text Case Changes ============ The case change commands described here work on text in the current buffer. *Note Character Case::, for case conversion commands that work on strings and characters. *Note Case Tables::, for how to customize which characters are upper or lower case and how to convert them. - Command: capitalize-region start end &optional buffer This function capitalizes all words in the region defined by START and END. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. The function returns `nil'. If one end of the region is in the middle of a word, the part of the word within the region is treated as an entire word. When `capitalize-region' is called interactively, START and END are point and the mark, with the smallest first. ---------- Buffer: foo ---------- This is the contents of the 5th foo. ---------- Buffer: foo ---------- (capitalize-region 1 44) => nil ---------- Buffer: foo ---------- This Is The Contents Of The 5th Foo. ---------- Buffer: foo ---------- - Command: downcase-region start end &optional buffer This function converts all of the letters in the region defined by START and END to lower case. The function returns `nil'. When `downcase-region' is called interactively, START and END are point and the mark, with the smallest first. - Command: upcase-region start end &optional buffer This function converts all of the letters in the region defined by START and END to upper case. The function returns `nil'. When `upcase-region' is called interactively, START and END are point and the mark, with the smallest first. - Command: capitalize-word count &optional buffer This function capitalizes COUNT words after point, moving point over as it does. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. If COUNT is negative, the function capitalizes the -COUNT previous words but does not move point. The value is `nil'. If point is in the middle of a word, the part of the word before point is ignored when moving forward. The rest is treated as an entire word. When `capitalize-word' is called interactively, COUNT is set to the numeric prefix argument. - Command: downcase-word count &optional buffer This function converts the COUNT words after point to all lower case, moving point over as it does. If COUNT is negative, it converts the -COUNT previous words but does not move point. The value is `nil'. When `downcase-word' is called interactively, COUNT is set to the numeric prefix argument. - Command: upcase-word count &optional buffer This function converts the COUNT words after point to all upper case, moving point over as it does. If COUNT is negative, it converts the -COUNT previous words but does not move point. The value is `nil'. When `upcase-word' is called interactively, COUNT is set to the numeric prefix argument.  File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text Text Properties =============== Text properties are an alternative interface to extents (*note Extents::), and are built on top of them. They are useful when you want to view textual properties as being attached to the characters themselves rather than to intervals of characters. The text property interface is compatible with FSF Emacs. Each character position in a buffer or a string can have a "text property list", much like the property list of a symbol (*note Property Lists::). The properties belong to a particular character at a particular place, such as, the letter `T' at the beginning of this sentence or the first `o' in `foo'--if the same character occurs in two different places, the two occurrences generally have different properties. Each property has a name and a value. Both of these can be any Lisp object, but the name is normally a symbol. The usual way to access the property list is to specify a name and ask what value corresponds to it. Note that FSF Emacs also looks at the `category' property to find defaults for text properties. We consider this too bogus to implement. Copying text between strings and buffers preserves the properties along with the characters; this includes such diverse functions as `substring', `insert', and `buffer-substring'. * Menu: * Examining Properties:: Looking at the properties of one character. * Changing Properties:: Setting the properties of a range of text. * Property Search:: Searching for where a property changes value. * Special Properties:: Particular properties with special meanings. * Saving Properties:: Saving text properties in files, and reading them back.  File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties Examining Text Properties ------------------------- The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use `get-text-property'. Use `text-properties-at' to get the entire property list of a character. *Note Property Search::, for functions to examine the properties of a number of characters at once. These functions handle both strings and buffers. (Keep in mind that positions in a string start from 0, whereas positions in a buffer start from 1.) - Function: get-text-property pos prop &optional object at-flag This function returns the value of the PROP property of the character after position POS in OBJECT (a buffer or string). The argument OBJECT is optional and defaults to the current buffer. - Function: get-char-property pos prop &optional object at-flag This function is like `get-text-property', except that it checks all extents, not just text-property extents. - Function: text-properties-at position &optional object This function returns the entire property list of the character at POSITION in the string or buffer OBJECT. If OBJECT is `nil', it defaults to the current buffer. - Variable: default-text-properties This variable holds a property list giving default values for text properties. Whenever a character does not specify a value for a property, the value stored in this list is used instead. Here is an example: (setq default-text-properties '(foo 69)) ;; Make sure character 1 has no properties of its own. (set-text-properties 1 2 nil) ;; What we get, when we ask, is the default value. (get-text-property 1 'foo) => 69  File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties Changing Text Properties ------------------------ The primitives for changing properties apply to a specified range of text. The function `set-text-properties' (see end of section) sets the entire property list of the text in that range; more often, it is useful to add, change, or delete just certain properties specified by name. Since text properties are considered part of the buffer's contents, and can affect how the buffer looks on the screen, any change in the text properties is considered a buffer modification. Buffer text property changes are undoable (*note Undo::). - Function: put-text-property start end prop value &optional object This function sets the PROP property to VALUE for the text between START and END in the string or buffer OBJECT. If OBJECT is `nil', it defaults to the current buffer. - Function: add-text-properties start end props &optional object This function modifies the text properties for the text between START and END in the string or buffer OBJECT. If OBJECT is `nil', it defaults to the current buffer. The argument PROPS specifies which properties to change. It should have the form of a property list (*note Property Lists::): a list whose elements include the property names followed alternately by the corresponding values. The return value is `t' if the function actually changed some property's value; `nil' otherwise (if PROPS is `nil' or its values agree with those in the text). For example, here is how to set the `comment' and `face' properties of a range of text: (add-text-properties START END '(comment t face highlight)) - Function: remove-text-properties start end props &optional object This function deletes specified text properties from the text between START and END in the string or buffer OBJECT. If OBJECT is `nil', it defaults to the current buffer. The argument PROPS specifies which properties to delete. It should have the form of a property list (*note Property Lists::): a list whose elements are property names alternating with corresponding values. But only the names matter--the values that accompany them are ignored. For example, here's how to remove the `face' property. (remove-text-properties START END '(face nil)) The return value is `t' if the function actually changed some property's value; `nil' otherwise (if PROPS is `nil' or if no character in the specified text had any of those properties). - Function: set-text-properties start end props &optional object This function completely replaces the text property list for the text between START and END in the string or buffer OBJECT. If OBJECT is `nil', it defaults to the current buffer. The argument PROPS is the new property list. It should be a list whose elements are property names alternating with corresponding values. After `set-text-properties' returns, all the characters in the specified range have identical properties. If PROPS is `nil', the effect is to get rid of all properties from the specified range of text. Here's an example: (set-text-properties START END nil) See also the function `buffer-substring-without-properties' (*note Buffer Contents::) which copies text from the buffer but does not copy its properties.  File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties Property Search Functions ------------------------- In typical use of text properties, most of the time several or many consecutive characters have the same value for a property. Rather than writing your programs to examine characters one by one, it is much faster to process chunks of text that have the same property value. Here are functions you can use to do this. They use `eq' for comparing property values. In all cases, OBJECT defaults to the current buffer. For high performance, it's very important to use the LIMIT argument to these functions, especially the ones that search for a single property--otherwise, they may spend a long time scanning to the end of the buffer, if the property you are interested in does not change. Remember that a position is always between two characters; the position returned by these functions is between two characters with different properties. - Function: next-property-change pos &optional object limit The function scans the text forward from position POS in the string or buffer OBJECT till it finds a change in some text property, then returns the position of the change. In other words, it returns the position of the first character beyond POS whose properties are not identical to those of the character just after POS. If LIMIT is non-`nil', then the scan ends at position LIMIT. If there is no property change before that point, `next-property-change' returns LIMIT. The value is `nil' if the properties remain unchanged all the way to the end of OBJECT and LIMIT is `nil'. If the value is non-`nil', it is a position greater than or equal to POS. The value equals POS only when LIMIT equals POS. Here is an example of how to scan the buffer by chunks of text within which all properties are constant: (while (not (eobp)) (let ((plist (text-properties-at (point))) (next-change (or (next-property-change (point) (current-buffer)) (point-max)))) Process text from point to NEXT-CHANGE... (goto-char next-change))) - Function: next-single-property-change pos prop &optional object limit The function scans the text forward from position POS in the string or buffer OBJECT till it finds a change in the PROP property, then returns the position of the change. In other words, it returns the position of the first character beyond POS whose PROP property differs from that of the character just after POS. If LIMIT is non-`nil', then the scan ends at position LIMIT. If there is no property change before that point, `next-single-property-change' returns LIMIT. The value is `nil' if the property remains unchanged all the way to the end of OBJECT and LIMIT is `nil'. If the value is non-`nil', it is a position greater than or equal to POS; it equals POS only if LIMIT equals POS. - Function: previous-property-change pos &optional object limit This is like `next-property-change', but scans backward from POS instead of forward. If the value is non-`nil', it is a position less than or equal to POS; it equals POS only if LIMIT equals POS. - Function: previous-single-property-change pos prop &optional object limit This is like `next-single-property-change', but scans backward from POS instead of forward. If the value is non-`nil', it is a position less than or equal to POS; it equals POS only if LIMIT equals POS. - Function: text-property-any start end prop value &optional object This function returns non-`nil' if at least one character between START and END has a property PROP whose value is VALUE. More precisely, it returns the position of the first such character. Otherwise, it returns `nil'. The optional fifth argument, OBJECT, specifies the string or buffer to scan. Positions are relative to OBJECT. The default for OBJECT is the current buffer. - Function: text-property-not-all start end prop value &optional object This function returns non-`nil' if at least one character between START and END has a property PROP whose value differs from VALUE. More precisely, it returns the position of the first such character. Otherwise, it returns `nil'. The optional fifth argument, OBJECT, specifies the string or buffer to scan. Positions are relative to OBJECT. The default for OBJECT is the current buffer.  File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties Properties with Special Meanings -------------------------------- The predefined properties are the same as those for extents. *Note Extent Properties::.  File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties Saving Text Properties in Files ------------------------------- You can save text properties in files, and restore text properties when inserting the files, using these two hooks: - Variable: write-region-annotate-functions This variable's value is a list of functions for `write-region' to run to encode text properties in some fashion as annotations to the text being written in the file. *Note Writing to Files::. Each function in the list is called with two arguments: the start and end of the region to be written. These functions should not alter the contents of the buffer. Instead, they should return lists indicating annotations to write in the file in addition to the text in the buffer. Each function should return a list of elements of the form `(POSITION . STRING)', where POSITION is an integer specifying the relative position in the text to be written, and STRING is the annotation to add there. Each list returned by one of these functions must be already sorted in increasing order by POSITION. If there is more than one function, `write-region' merges the lists destructively into one sorted list. When `write-region' actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer. - Variable: after-insert-file-functions This variable holds a list of functions for `insert-file-contents' to call after inserting a file's contents. These functions should scan the inserted text for annotations, and convert them to the text properties they stand for. Each function receives one argument, the length of the inserted text; point indicates the start of that text. The function should scan that text for annotations, delete them, and create the text properties that the annotations specify. The function should return the updated length of the inserted text, as it stands after those changes. The value returned by one function becomes the argument to the next function. These functions should always return with point at the beginning of the inserted text. The intended use of `after-insert-file-functions' is for converting some sort of textual annotations into actual text properties. But other uses may be possible. We invite users to write Lisp programs to store and retrieve text properties in files, using these hooks, and thus to experiment with various data formats and find good ones. Eventually we hope users will produce good, general extensions we can install in Emacs. We suggest not trying to handle arbitrary Lisp objects as property names or property values--because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode. *Note Format Conversion::, for a related feature.  File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text Substituting for a Character Code ================================= The following functions replace characters within a specified region based on their character codes. - Function: subst-char-in-region start end old-char new-char &optional noundo This function replaces all occurrences of the character OLD-CHAR with the character NEW-CHAR in the region of the current buffer defined by START and END. If NOUNDO is non-`nil', then `subst-char-in-region' does not record the change for undo and does not mark the buffer as modified. This feature is used for controlling selective display (*note Selective Display::). `subst-char-in-region' does not move point and returns `nil'. ---------- Buffer: foo ---------- This is the contents of the buffer before. ---------- Buffer: foo ---------- (subst-char-in-region 1 20 ?i ?X) => nil ---------- Buffer: foo ---------- ThXs Xs the contents of the buffer before. ---------- Buffer: foo ---------- - Function: translate-region start end table This function applies a translation table to the characters in the buffer between positions START and END. The translation table TABLE can be either a string, a vector, or a char-table. If TABLE is a string, its Nth element is the mapping for the character with code N. If TABLE is a vector, its Nth element is the mapping for character with code N. Legal mappings are characters, strings, or `nil' (meaning don't replace.) If TABLE is a char-table, its elements describe the mapping between characters and their replacements. The char-table should be of type `char' or `generic'. When the TABLE is a string or vector and its length is less than the total number of characters (256 without Mule), any characters with codes larger than the length of TABLE are not altered by the translation. The return value of `translate-region' is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table. *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only to be a string. This is still the case in FSF Emacs. The following example creates a char-table that is passed to `translate-region', which translates character `a' to `the letter a', removes character `b', and translates character `c' to newline. ---------- Buffer: foo ---------- Here is a sentence in the buffer. ---------- Buffer: foo ---------- (let ((table (make-char-table 'generic))) (put-char-table ?a "the letter a" table) (put-char-table ?b "" table) (put-char-table ?c ?\n table) (translate-region (point-min) (point-max) table)) => 3 ---------- Buffer: foo ---------- Here is the letter a senten e in the uffer. ---------- Buffer: foo ----------  File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text Registers ========= A register is a sort of variable used in XEmacs editing that can hold a marker, a string, a rectangle, a window configuration (of one frame), or a frame configuration (of all frames). Each register is named by a single character. All characters, including control and meta characters (but with the exception of `C-g'), can be used to name registers. Thus, there are 255 possible registers. A register is designated in Emacs Lisp by a character that is its name. The functions in this section return unpredictable values unless otherwise stated. - Variable: register-alist This variable is an alist of elements of the form `(NAME . CONTENTS)'. Normally, there is one element for each XEmacs register that has been used. The object NAME is a character (an integer) identifying the register. The object CONTENTS is a string, marker, or list representing the register contents. A string represents text stored in the register. A marker represents a position. A list represents a rectangle; its elements are strings, one per line of the rectangle. - Function: get-register register This function returns the contents of the register REGISTER, or `nil' if it has no contents. - Function: set-register register value This function sets the contents of register REGISTER to VALUE. A register can be set to any value, but the other register functions expect only certain data types. The return value is VALUE. - Command: view-register register This command displays what is contained in register REGISTER. - Command: insert-register register &optional beforep This command inserts contents of register REGISTER into the current buffer. Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument BEFOREP is non-`nil', it puts the mark before and point after. You can pass a non-`nil' second argument BEFOREP to this function interactively by supplying any prefix argument. If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted in the current line and underneath it on successive lines. If the register contains something other than saved text (a string) or a rectangle (a list), currently useless things happen. This may be changed in the future.  File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text Transposition of Text ===================== This subroutine is used by the transposition commands. - Function: transpose-regions start1 end1 start2 end2 &optional leave-markers This function exchanges two nonoverlapping portions of the buffer. Arguments START1 and END1 specify the bounds of one portion and arguments START2 and END2 specify the bounds of the other portion. Normally, `transpose-regions' relocates markers with the transposed text; a marker previously positioned within one of the two transposed portions moves along with that portion, thus remaining between the same two characters in their new position. However, if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do this--it leaves all markers unrelocated.  File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text Change Hooks ============ These hook variables let you arrange to take notice of all changes in all buffers (or in a particular buffer, if you make them buffer-local). The functions you use in these hooks should save and restore the match data if they do anything that uses regular expressions; otherwise, they will interfere in bizarre ways with the editing operations that call them. Buffer changes made while executing the following hooks don't themselves cause any change hooks to be invoked. - Variable: before-change-functions This variable holds a list of a functions to call before any buffer modification. Each function gets two arguments, the beginning and end of the region that is about to change, represented as integers. The buffer that is about to change is always the current buffer. - Variable: after-change-functions This variable holds a list of a functions to call after any buffer modification. Each function receives three arguments: the beginning and end of the region just changed, and the length of the text that existed before the change. (To get the current length, subtract the region beginning from the region end.) All three arguments are integers. The buffer that's about to change is always the current buffer. - Variable: before-change-function This obsolete variable holds one function to call before any buffer modification (or `nil' for no function). It is called just like the functions in `before-change-functions'. - Variable: after-change-function This obsolete variable holds one function to call after any buffer modification (or `nil' for no function). It is called just like the functions in `after-change-functions'. - Variable: first-change-hook This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state.  File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text Textual transformations--MD5 and base64 support =============================================== Some textual operations inherently require examining each character in turn, and performing arithmetic operations on them. Such operations can, of course, be implemented in Emacs Lisp, but tend to be very slow for large portions of text or data. This is why some of them are implemented in C, with an appropriate interface for Lisp programmers. Examples of algorithms thus provided are MD5 and base64 support. MD5 is an algorithm for calculating message digests, as described in rfc1321. Given a message of arbitrary length, MD5 produces a 128-bit "fingerprint" ("message digest") corresponding to that message. It is considered computationally infeasible to produce two messages having the same MD5 digest, or to produce a message having a prespecified target digest. MD5 is used heavily by various authentication schemes. Emacs Lisp interface to MD5 consists of a single function `md5': - Function: md5 object &optional start end coding noerror This function returns the MD5 message digest of OBJECT, a buffer or string. Optional arguments START and END denote positions for computing the digest of a portion of OBJECT. The optional CODING argument specifies the coding system the text is to be represented in while computing the digest. If unspecified, it defaults to the current format of the data, or is guessed. If NOERROR is non-`nil', silently assume binary coding if the guesswork fails. Normally, an error is signaled in such case. CODING and NOERROR arguments are meaningful only in XEmacsen with file-coding or Mule support. Otherwise, they are ignored. Some examples of usage: ;; Calculate the digest of the entire buffer (md5 (current-buffer)) => "8842b04362899b1cda8d2d126dc11712" ;; Calculate the digest of the current line (md5 (current-buffer) (point-at-bol) (point-at-eol)) => "60614d21e9dee27dfdb01fa4e30d6d00" ;; Calculate the digest of your name and email address (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address))) => "0a2188c40fd38922d941fe6032fce516" Base64 is a portable encoding for arbitrary sequences of octets, in a form that need not be readable by humans. It uses a 65-character subset of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode binary bodies, and to encode binary characters in message headers. The Lisp interface to base64 consists of four functions: - Command: base64-encode-region start end &optional no-line-break This function encodes the region between START and END of the current buffer to base64 format. This means that the original region is deleted, and replaced with its base64 equivalent. Normally, encoded base64 output is multi-line, with 76-character lines. If NO-LINE-BREAK is non-`nil', newlines will not be inserted, resulting in single-line output. Mule note: you should make sure that you convert the multibyte characters (those that do not fit into 0-255 range) to something else, because they cannot be meaningfully converted to base64. If the `base64-encode-region' encounters such characters, it will signal an error. `base64-encode-region' returns the length of the encoded text. ;; Encode the whole buffer in base64 (base64-encode-region (point-min) (point-max)) The function can also be used interactively, in which case it works on the currently active region. - Function: base64-encode-string string &optional no-line-break This function encodes STRING to base64, and returns the encoded string. Normally, encoded base64 output is multi-line, with 76-character lines. If NO-LINE-BREAK is non-`nil', newlines will not be inserted, resulting in single-line output. For Mule, the same considerations apply as for `base64-encode-region'. (base64-encode-string "fubar") => "ZnViYXI=" - Command: base64-decode-region start end This function decodes the region between START and END of the current buffer. The region should be in base64 encoding. If the region was decoded correctly, `base64-decode-region' returns the length of the decoded region. If the decoding failed, `nil' is returned. ;; Decode a base64 buffer, and replace it with the decoded version (base64-decode-region (point-min) (point-max)) - Function: base64-decode-string string This function decodes STRING to base64, and returns the decoded string. STRING should be valid base64-encoded text. If encoding was not possible, `nil' is returned. (base64-decode-string "ZnViYXI=") => "fubar" (base64-decode-string "totally bogus") => nil  File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top Searching and Matching ********************** XEmacs provides two ways to search through a buffer for specified text: exact string searches and regular expression searches. After a regular expression search, you can examine the "match data" to determine which text matched the whole regular expression or various portions of it. * Menu: * String Search:: Search for an exact match. * Regular Expressions:: Describing classes of strings. * Regexp Search:: Searching for a match for a regexp. * POSIX Regexps:: Searching POSIX-style for the longest match. * Search and Replace:: Internals of `query-replace'. * Match Data:: Finding out which part of the text matched various parts of a regexp, after regexp search. * Searching and Case:: Case-independent or case-significant searching. * Standard Regexps:: Useful regexps for finding sentences, pages,... The `skip-chars...' functions also perform a kind of searching. *Note Skipping Characters::.  File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching Searching for Strings ===================== These are the primitive functions for searching through the text in a buffer. They are meant for use in programs, but you may call them interactively. If you do so, they prompt for the search string; LIMIT and NOERROR are set to `nil', and COUNT is set to 1. - Command: search-forward string &optional limit noerror count buffer This function searches forward from point for an exact match for STRING. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on NOERROR (see below). In the following example, point is initially at the beginning of the line. Then `(search-forward "fox")' moves point after the last letter of `fox': ---------- Buffer: foo ---------- -!-The quick brown fox jumped over the lazy dog. ---------- Buffer: foo ---------- (search-forward "fox") => 20 ---------- Buffer: foo ---------- The quick brown fox-!- jumped over the lazy dog. ---------- Buffer: foo ---------- The argument LIMIT specifies the upper bound to the search. (It must be a position in the current buffer.) No match extending after that position is accepted. If LIMIT is omitted or `nil', it defaults to the end of the accessible portion of the buffer. What happens when the search fails depends on the value of NOERROR. If NOERROR is `nil', a `search-failed' error is signaled. If NOERROR is `t', `search-forward' returns `nil' and does nothing. If NOERROR is neither `nil' nor `t', then `search-forward' moves point to the upper bound and returns `nil'. (It would be more consistent now to return the new position of point in that case, but some programs may depend on a value of `nil'.) If COUNT is supplied (it must be an integer), then the search is repeated that many times (each time starting at the end of the previous time's match). If COUNT is negative, the search direction is backward. If the successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails. BUFFER is the buffer to search in, and defaults to the current buffer. - Command: search-backward string &optional limit noerror count buffer This function searches backward from point for STRING. It is just like `search-forward' except that it searches backwards and leaves point at the beginning of the match. - Command: word-search-forward string &optional limit noerror count buffer This function searches forward from point for a "word" match for STRING. If it finds a match, it sets point to the end of the match found, and returns the new value of point. Word matching regards STRING as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word `ball' does not match the word `balls'), but the details of punctuation and spacing are ignored (searching for `ball boy' does match `ball. Boy!'). In this example, point is initially at the beginning of the buffer; the search leaves it between the `y' and the `!'. ---------- Buffer: foo ---------- -!-He said "Please! Find the ball boy!" ---------- Buffer: foo ---------- (word-search-forward "Please find the ball, boy.") => 35 ---------- Buffer: foo ---------- He said "Please! Find the ball boy-!-!" ---------- Buffer: foo ---------- If LIMIT is non-`nil' (it must be a position in the current buffer), then it is the upper bound to the search. The match found must not extend after that position. If NOERROR is `nil', then `word-search-forward' signals an error if the search fails. If NOERROR is `t', then it returns `nil' instead of signaling an error. If NOERROR is neither `nil' nor `t', it moves point to LIMIT (or the end of the buffer) and returns `nil'. If COUNT is non-`nil', then the search is repeated that many times. Point is positioned at the end of the last match. BUFFER is the buffer to search in, and defaults to the current buffer. - Command: word-search-backward string &optional limit noerror count buffer This function searches backward from point for a word match to STRING. This function is just like `word-search-forward' except that it searches backward and normally leaves point at the beginning of the match.  File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching Regular Expressions =================== A "regular expression" ("regexp", for short) is a pattern that denotes a (possibly infinite) set of strings. Searching for matches for a regexp is a very powerful operation. This section explains how to write regexps; the following section says how to search for them. To gain a thorough understanding of regular expressions and how to use them to best advantage, we recommend that you study `Mastering Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, 1997'. (It's known as the "Hip Owls" book, because of the picture on its cover.) You might also read the manuals to *Note (gawk)Top::, *Note (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of regular expressions. The XEmacs regular expression syntax most closely resembles that of `ed', or `grep', the GNU versions of which all utilize the GNU `regex' library. XEmacs' version of `regex' has recently been extended with some Perl-like capabilities, described in the next section. * Menu: * Syntax of Regexps:: Rules for writing regular expressions. * Regexp Example:: Illustrates regular expression syntax.  File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions Syntax of Regular Expressions ----------------------------- Regular expressions have a syntax in which a few characters are special constructs and the rest are "ordinary". An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and `\'; no new special characters will be defined in the future. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it. For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does _not_ match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'. Any two regular expressions A and B can be concatenated. The result is a regular expression that matches a string if A matches some amount of the beginning of that string and B matches the rest of the string. As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something more powerful, you need to use one of the special characters. Here is a list of them: `. (Period)' is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'. `*' is not a construct by itself; it is a quantifying suffix operator that means to repeat the preceding regular expression as many times as possible. In `fo*', the `*' applies to the `o', so `fo*' matches one `f' followed by any number of `o's. The case of zero `o's is allowed: `fo*' does match `f'. `*' always applies to the _smallest_ possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found; it is "greedy". Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the `*'-modified construct in case that makes it possible to match the rest of the pattern. For example, in matching `ca*ar' against the string `caaar', the `a*' first tries to match all three `a's; but the rest of the pattern is `ar' and there is only `r' left to match, so this try fails. The next alternative is for `a*' to match only two `a's. With this choice, the rest of the regexp matches successfully. Nested repetition operators can be extremely slow if they specify backtracking loops. For example, it could take hours for the regular expression `\(x+y*\)*a' to match the sequence `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because Emacs must try each imaginable way of grouping the 35 `x''s before concluding that none of them can work. To make sure your regular expressions run fast, check nested repetitions carefully. `+' is a quantifying suffix operator similar to `*' except that the preceding expression must match at least once. It is also "greedy". So, for example, `ca+r' matches the strings `car' and `caaaar' but not the string `cr', whereas `ca*r' matches all three strings. `?' is a quantifying suffix operator similar to `*', except that the preceding expression can match either once or not at all. For example, `ca?r' matches `car' or `cr', but does not match anything else. `*?' works just like `*', except that rather than matching the longest match, it matches the shortest match. `*?' is known as a "non-greedy" quantifier, a regexp construct borrowed from Perl. This construct is very useful for when you want to match the text inside a pair of delimiters. For instance, `/\*.*?\*/' will match C comments in a string. This could not easily be achieved without the use of a non-greedy quantifier. This construct has not been available prior to XEmacs 20.4. It is not available in FSF Emacs. `+?' is the non-greedy version of `+'. `??' is the non-greedy version of `?'. `\{n,m\}' serves as an interval quantifier, analogous to `*' or `+', but specifies that the expression must match at least N times, but no more than M times. This syntax is supported by most Unix regexp utilities, and has been introduced to XEmacs for the version 20.3. Unfortunately, the non-greedy version of this quantifier does not exist currently, although it does in Perl. `[ ... ]' `[' begins a "character set", which is terminated by a `]'. In the simplest case, the characters between the two brackets form the set. Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' matches any string composed of just `a's and `d's (including the empty string), from which it follows that `c[ad]*r' matches `cr', `car', `cdr', `caddaar', etc. The usual regular expression special characters are not special inside a character set. A completely different set of special characters exists inside character sets: `]', `-' and `^'. `-' is used for ranges of characters. To write a range, write two characters with a `-' between them. Thus, `[a-z]' matches any lower case letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower case letter or `$', `%', or a period. To include a `]' in a character set, make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', write `-' as the first character in the set, or put it immediately after a range. (You can replace one individual character C with the range `C-C' to make a place to put the `-'.) There is no way to write a set containing just `-' and `]'. To include `^' in a set, put it anywhere but at the beginning of the set. `[^ ... ]' `[^' begins a "complement character set", which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters _except_ letters and digits. `^' is not special in a character set unless it is the first character. The character following the `^' is treated as if it were first (thus, `-' and `]' are not special there). Note that a complement character set can match a newline, unless newline is mentioned as one of the characters not to match. `^' is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' that occurs at the beginning of a line. When matching a string instead of a buffer, `^' matches at the beginning of the string or after a newline character `\n'. `$' is similar to `^' but matches only at the end of a line. Thus, `x+$' matches a string of one `x' or more at the end of a line. When matching a string instead of a buffer, `$' matches at the end of the string or before a newline character `\n'. `\' has two functions: it quotes the special characters (including `\'), and it introduces additional special constructs. Because `\' quotes special characters, `\$' is a regular expression that matches only `$', and `\[' is a regular expression that matches only `[', and so on. Note that `\' also has special meaning in the read syntax of Lisp strings (*note String Type::), and must be quoted with `\'. For example, the regular expression that matches the `\' character is `\\'. To write a Lisp string that contains the characters `\\', Lisp syntax requires you to quote each `\' with another `\'. Therefore, the read syntax for a regular expression matching `\' is `"\\\\"'. *Please note:* For historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears. For the most part, `\' followed by any character matches only that character. However, there are several exceptions: characters that, when preceded by `\', are special constructs. Such characters are always ordinary when encountered on their own. Here is a table of `\' constructs: `\|' specifies an alternative. Two regular expressions A and B with `\|' in between form an expression that matches anything that either A or B matches. Thus, `foo\|bar' matches either `foo' or `bar' but no other string. `\|' applies to the largest possible surrounding expressions. Only a surrounding `\( ... \)' grouping can limit the grouping power of `\|'. Full backtracking capability exists to handle multiple uses of `\|'. `\( ... \)' is a grouping construct that serves three purposes: 1. To enclose a set of `\|' alternatives for other operations. Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. 2. To enclose an expression for a suffix operator such as `*' to act on. Thus, `ba\(na\)*' matches `bananana', etc., with any (zero or more) number of `na' strings. 3. To record a matched substring for future reference. This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that happens to be assigned as a second meaning to the same `\( ... \)' construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature: `\DIGIT' matches the same text that matched the DIGITth occurrence of a `\( ... \)' construct. In other words, after the end of a `\( ... \)' construct. the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use `\' followed by DIGIT to match that same text, whatever it may have been. The strings matching the first nine `\( ... \)' constructs appearing in a regular expression are assigned numbers 1 through 9 in the order that the open parentheses appear in the regular expression. So you can use `\1' through `\9' to refer to the text matched by the corresponding `\( ... \)' constructs. For example, `\(.*\)\1' matches any newline-free string that is composed of two identical halves. The `\(.*\)' matches the first half, which may be anything, but the `\1' that follows must match the same exact text. `\(?: ... \)' is called a "shy" grouping operator, and it is used just like `\( ... \)', except that it does not cause the matched substring to be recorded for future reference. This is useful when you need a lot of grouping `\( ... \)' constructs, but only want to remember one or two - or if you have more than nine groupings and need to use backreferences to refer to the groupings at the end. Using `\(?: ... \)' rather than `\( ... \)' when you don't need the captured substrings ought to speed up your programs some, since it shortens the code path followed by the regular expression engine, as well as the amount of memory allocation and string copying it must do. The actual performance gain to be observed has not been measured or quantified as of this writing. The shy grouping operator has been borrowed from Perl, and has not been available prior to XEmacs 20.3, nor is it available in FSF Emacs. `\w' matches any word-constituent character. The editor syntax table determines which characters these are. *Note Syntax Tables::. `\W' matches any character that is not a word constituent. `\sCODE' matches any character whose syntax is CODE. Here CODE is a character that represents a syntax code: thus, `w' for word constituent, `-' for whitespace, `(' for open parenthesis, etc. *Note Syntax Tables::, for a list of syntax codes and the characters that stand for them. `\SCODE' matches any character whose syntax is not CODE. The following regular expression constructs match the empty string--that is, they don't use up any characters--but whether they match depends on the context. `\`' matches the empty string, but only at the beginning of the buffer or string being matched against. `\'' matches the empty string, but only at the end of the buffer or string being matched against. `\=' matches the empty string, but only at point. (This construct is not defined when matching against a string.) `\b' matches the empty string, but only at the beginning or end of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a separate word. `\bballs?\b' matches `ball' or `balls' as a separate word. `\B' matches the empty string, but _not_ at the beginning or end of a word. `\<' matches the empty string, but only at the beginning of a word. `\>' matches the empty string, but only at the end of a word. Not every string is a valid regular expression. For example, a string with unbalanced square brackets is invalid (with a few exceptions, such as `[]]'), and so is a string that ends with a single `\'. If an invalid regular expression is passed to any of the search functions, an `invalid-regexp' error is signaled. - Function: regexp-quote string This function returns a regular expression string that matches exactly STRING and nothing else. This allows you to request an exact string match when calling a function that wants a regular expression. (regexp-quote "^The cat$") => "\\^The cat\\$" One use of `regexp-quote' is to combine an exact string match with context described as a regular expression. For example, this searches for the string that is the value of `string', surrounded by whitespace: (re-search-forward (concat "\\s-" (regexp-quote string) "\\s-"))  File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions Complex Regexp Example ---------------------- Here is a complicated regexp, used by XEmacs to recognize the end of a sentence together with any whitespace that follows. It is the value of the variable `sentence-end'. First, we show the regexp as a string in Lisp syntax to distinguish spaces from tab characters. The string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the string, `\\' for a backslash as part of the string, `\t' for a tab and `\n' for a newline. "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" In contrast, if you evaluate the variable `sentence-end', you will see the following: sentence-end => "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[ ]*" In this output, tab and newline appear as themselves. This regular expression contains four parts in succession and can be deciphered as follows: `[.?!]' The first part of the pattern is a character set that matches any one of three characters: period, question mark, and exclamation mark. The match must begin with one of these three characters. `[]\"')}]*' The second part of the pattern matches any closing braces and quotation marks, zero or more of them, that may follow the period, question mark or exclamation mark. The `\"' is Lisp syntax for a double-quote in a string. The `*' at the end indicates that the immediately preceding regular expression (a character set, in this case) may be repeated zero or more times. `\\($\\| $\\|\t\\| \\)' The third part of the pattern matches the whitespace that follows the end of a sentence: the end of a line, or a tab, or two spaces. The double backslashes mark the parentheses and vertical bars as regular expression syntax; the parentheses delimit a group and the vertical bars separate alternatives. The dollar sign is used to match the end of a line. `[ \t\n]*' Finally, the last part of the pattern matches any additional whitespace beyond the minimum needed to end a sentence.  File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching Regular Expression Searching ============================ In XEmacs, you can search for the next match for a regexp either incrementally or not. Incremental search commands are described in the `The XEmacs Lisp Reference Manual'. *Note Regular Expression Search: (xemacs)Regexp Search. Here we describe only the search functions useful in programs. The principal one is `re-search-forward'. - Command: re-search-forward regexp &optional limit noerror count buffer This function searches forward in the current buffer for a string of text that is matched by the regular expression REGEXP. The function skips over any amount of text that is not matched by REGEXP, and leaves point at the end of the first match found. It returns the new value of point. If LIMIT is non-`nil' (it must be a position in the current buffer), then it is the upper bound to the search. No match extending after that position is accepted. What happens when the search fails depends on the value of NOERROR. If NOERROR is `nil', a `search-failed' error is signaled. If NOERROR is `t', `re-search-forward' does nothing and returns `nil'. If NOERROR is neither `nil' nor `t', then `re-search-forward' moves point to LIMIT (or the end of the buffer) and returns `nil'. If COUNT is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). If these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails. In the following example, point is initially before the `T'. Evaluating the search call moves point to the end of that line (between the `t' of `hat' and the newline). ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (re-search-forward "[a-z]+" nil t 5) => 27 ---------- Buffer: foo ---------- I read "The cat in the hat-!- comes back" twice. ---------- Buffer: foo ---------- - Command: re-search-backward regexp &optional limit noerror count buffer This function searches backward in the current buffer for a string of text that is matched by the regular expression REGEXP, leaving point at the beginning of the first text found. This function is analogous to `re-search-forward', but they are not simple mirror images. `re-search-forward' finds the match whose beginning is as close as possible to the starting point. If `re-search-backward' were a perfect mirror image, it would find the match whose end is as close as possible. However, in fact it finds the match whose beginning is as close as possible. The reason is that matching a regular expression at a given spot always works from beginning to end, and starts at a specified beginning position. A true mirror-image of `re-search-forward' would require a special feature for matching regexps from end to beginning. It's not worth the trouble of implementing that. - Function: string-match regexp string &optional start buffer This function returns the index of the start of the first match for the regular expression REGEXP in STRING, or `nil' if there is no match. If START is non-`nil', the search starts at that index in STRING. Optional arg BUFFER controls how case folding is done (according to the value of `case-fold-search' in BUFFER and BUFFER's case tables) and defaults to the current buffer. For example, (string-match "quick" "The quick brown fox jumped quickly.") => 4 (string-match "quick" "The quick brown fox jumped quickly." 8) => 27 The index of the first character of the string is 0, the index of the second character is 1, and so on. After this function returns, the index of the first character beyond the match is available as `(match-end 0)'. *Note Match Data::. (string-match "quick" "The quick brown fox jumped quickly." 8) => 27 (match-end 0) => 32 - Function: split-string string &optional pattern This function splits STRING to substrings delimited by PATTERN, and returns a list of substrings. If PATTERN is omitted, it defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by white-space. (split-string "foo bar") => ("foo" "bar") (split-string "something") => ("something") (split-string "a:b:c" ":") => ("a" "b" "c") (split-string ":a::b:c" ":") => ("" "a" "" "b" "c") - Function: split-path path This function splits a search path into a list of strings. The path components are separated with the characters specified with `path-separator'. Under Unix, `path-separator' will normally be `:', while under Windows, it will be `;'. - Function: looking-at regexp &optional buffer This function determines whether the text in the current buffer directly following point matches the regular expression REGEXP. "Directly following" means precisely that: the search is "anchored" and it can succeed only starting with the first character following point. The result is `t' if so, `nil' otherwise. This function does not move point, but it updates the match data, which you can access using `match-beginning' and `match-end'. *Note Match Data::. In this example, point is located directly before the `T'. If it were anywhere else, the result would be `nil'. ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (looking-at "The cat in the hat$") => t  File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching POSIX Regular Expression Searching ================================== The usual regular expression functions do backtracking when necessary to handle the `\|' and repetition constructs, but they continue this only until they find _some_ match. Then they succeed and report the first match found. This section describes alternative search functions which perform the full backtracking specified by the POSIX standard for regular expression matching. They continue backtracking until they have tried all possibilities and found all matches, so they can report the longest match, as required by POSIX. This is much slower, so use these functions only when you really need the longest match. In Emacs versions prior to 19.29, these functions did not exist, and the functions described above implemented full POSIX backtracking. - Command: posix-search-forward regexp &optional limit noerror count buffer This is like `re-search-forward' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. - Command: posix-search-backward regexp &optional limit noerror count buffer This is like `re-search-backward' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. - Function: posix-looking-at regexp &optional buffer This is like `looking-at' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. - Function: posix-string-match regexp string &optional start buffer This is like `string-match' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. Optional arg BUFFER controls how case folding is done (according to the value of `case-fold-search' in BUFFER and BUFFER's case tables) and defaults to the current buffer.  File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching Search and Replace ================== - Function: perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map This function is the guts of `query-replace' and related commands. It searches for occurrences of FROM-STRING and replaces some or all of them. If QUERY-FLAG is `nil', it replaces all occurrences; otherwise, it asks the user what to do about each one. If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a regular expression; otherwise, it must match literally. If DELIMITED-FLAG is non-`nil', then only replacements surrounded by word boundaries are considered. The argument REPLACEMENTS specifies what to replace occurrences with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order. If REPEAT-COUNT is non-`nil', it should be an integer. Then it specifies how many times to use each of the strings in the REPLACEMENTS list before advancing cyclicly to the next one. Normally, the keymap `query-replace-map' defines the possible user responses for queries. The argument MAP, if non-`nil', is a keymap to use instead of `query-replace-map'. - Variable: query-replace-map This variable holds a special keymap that defines the valid user responses for `query-replace' and related functions, as well as `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways: * The "key bindings" are not commands, just symbols that are meaningful to the functions that use this map. * Prefix keys are not supported; each key binding must be for a single event key sequence. This is because the functions don't use read key sequence to get the input; instead, they read a single event and look it up "by hand." Here are the meaningful "bindings" for `query-replace-map'. Several of them are meaningful only for `query-replace' and friends. `act' Do take the action being considered--in other words, "yes." `skip' Do not take action for this question--in other words, "no." `exit' Answer this question "no," and give up on the entire series of questions, assuming that the answers will be "no." `act-and-exit' Answer this question "yes," and give up on the entire series of questions, assuming that subsequent answers will be "no." `act-and-show' Answer this question "yes," but show the results--don't advance yet to the next question. `automatic' Answer this question and all subsequent questions in the series with "yes," without further user interaction. `backup' Move back to the previous place that a question was asked about. `edit' Enter a recursive edit to deal with this question--instead of any other action that would normally be taken. `delete-and-edit' Delete the text being considered, then enter a recursive edit to replace it. `recenter' Redisplay and center the window, then ask the same question again. `quit' Perform a quit right away. Only `y-or-n-p' and related functions use this answer. `help' Display some help, then ask again.  File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching The Match Data ============== XEmacs keeps track of the positions of the start and end of segments of text found during a regular expression search. This means, for example, that you can search for a complex pattern, such as a date in an Rmail message, and then extract parts of the match under control of the pattern. Because the match data normally describe the most recent search only, you must be careful not to do another search inadvertently between the search you wish to refer back to and the use of the match data. If you can't avoid another intervening search, you must save and restore the match data around it, to prevent it from being overwritten. * Menu: * Simple Match Data:: Accessing single items of match data, such as where a particular subexpression started. * Replacing Match:: Replacing a substring that was matched. * Entire Match Data:: Accessing the entire match data at once, as a list. * Saving Match Data:: Saving and restoring the match data.  File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data Simple Match Data Access ------------------------ This section explains how to use the match data to find out what was matched by the last search or match operation. You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The COUNT argument in the functions below specifies which. If COUNT is zero, you are asking about the entire match. If COUNT is positive, it specifies which subexpression you want. Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, `\(...\)'. The COUNTth subexpression is found by counting occurrences of `\(' from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions--after a simple string search, the only information available is about the entire match. - Function: match-string count &optional in-string This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if COUNT is zero, or just the portion corresponding to the COUNTth parenthetical subexpression, if COUNT is positive. If COUNT is out of range, or if that subexpression didn't match anything, the value is `nil'. If the last such operation was done against a string with `string-match', then you should pass the same string as the argument IN-STRING. Otherwise, after a buffer search or match, you should omit IN-STRING or pass `nil' for it; but you should make sure that the current buffer when you call `match-string' is the one in which you did the searching or matching. - Function: match-beginning count This function returns the position of the start of text matched by the last regular expression searched for, or a subexpression of it. If COUNT is zero, then the value is the position of the start of the entire match. Otherwise, COUNT specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression. The value is `nil' for a subexpression inside a `\|' alternative that wasn't used in the match. - Function: match-end count This function is like `match-beginning' except that it returns the position of the end of the match, rather than the position of the beginning. Here is an example of using the match data, with a comment showing the positions within the text: (string-match "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.") ;0123456789 => 4 (match-string 0 "The quick fox jumped quickly.") => "quick" (match-string 1 "The quick fox jumped quickly.") => "qu" (match-string 2 "The quick fox jumped quickly.") => "ick" (match-beginning 1) ; The beginning of the match => 4 ; with `qu' is at index 4. (match-beginning 2) ; The beginning of the match => 6 ; with `ick' is at index 6. (match-end 1) ; The end of the match => 6 ; with `qu' is at index 6. (match-end 2) ; The end of the match => 9 ; with `ick' is at index 9. Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word `in'. The beginning of the entire match is at the 9th character of the buffer (`T'), and the beginning of the match for the first subexpression is at the 13th character (`c'). (list (re-search-forward "The \\(cat \\)") (match-beginning 0) (match-beginning 1)) => (9 9 13) ---------- Buffer: foo ---------- I read "The cat -!-in the hat comes back" twice. ^ ^ 9 13 ---------- Buffer: foo ---------- (In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)  File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data Replacing the Text That Matched ------------------------------- This function replaces the text matched by the last search with REPLACEMENT. - Function: replace-match replacement &optional fixedcase literal string strbuffer This function replaces the text in the buffer (or in STRING) that was matched by the last search. It replaces that text with REPLACEMENT. If you did the last search in a buffer, you should specify `nil' for STRING. Then `replace-match' does the replacement by editing the buffer; it leaves point at the end of the replacement text, and returns `t'. If you did the search in a string, pass the same string as STRING. Then `replace-match' does the replacement by constructing and returning a new string. If the fourth argument STRING is a string, fifth argument STRBUFFER specifies the buffer to be used for syntax-table and case-table lookup and defaults to the current buffer. When STRING is not a string, the buffer that the match occurred in has automatically been remembered and you do not need to specify it. If FIXEDCASE is non-`nil', then the case of the replacement text is not changed; otherwise, the replacement text is converted to a different case depending upon the capitalization of the text to be replaced. If the original text is all upper case, the replacement text is converted to upper case. If the first word of the original text is capitalized, then the first word of the replacement text is capitalized. If the original text contains just one word, and that word is a capital letter, `replace-match' considers this a capitalized first word rather than all upper case. If `case-replace' is `nil', then case conversion is not done, regardless of the value of FIXEDCASE. *Note Searching and Case::. If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as it is, the only alterations being case changes as needed. If it is `nil' (the default), then the character `\' is treated specially. If a `\' appears in REPLACEMENT, then it must be part of one of the following sequences: `\&' `\&' stands for the entire text being replaced. `\N' `\N', where N is a digit, stands for the text that matched the Nth subexpression in the original regexp. Subexpressions are those expressions grouped inside `\(...\)'. `\\' `\\' stands for a single `\' in the replacement text.  File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data Accessing the Entire Match Data ------------------------------- The functions `match-data' and `set-match-data' read or write the entire match data, all at once. - Function: match-data &optional integers reuse This function returns a newly constructed list containing all the information on what text the last search matched. Element zero is the position of the beginning of the match for the whole expression; element one is the position of the end of the match for the expression. The next two elements are the positions of the beginning and end of the match for the first subexpression, and so on. In general, element number 2N corresponds to `(match-beginning N)'; and element number 2N + 1 corresponds to `(match-end N)'. All the elements are markers or `nil' if matching was done on a buffer, and all are integers or `nil' if matching was done on a string with `string-match'. However, if the optional first argument INTEGERS is non-`nil', always use integers (rather than markers) to represent buffer positions. If the optional second argument REUSE is a list, reuse it as part of the value. If REUSE is long enough to hold all the values, and if INTEGERS is non-`nil', no new lisp objects are created. As always, there must be no possibility of intervening searches between the call to a search function and the call to `match-data' that is intended to access the match data for that search. (match-data) => (# # # #) - Function: set-match-data match-list This function sets the match data from the elements of MATCH-LIST, which should be a list that was the value of a previous call to `match-data'. If MATCH-LIST refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way. `store-match-data' is an alias for `set-match-data'.  File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data Saving and Restoring the Match Data ----------------------------------- When you call a function that may do a search, you may need to save and restore the match data around that call, if you want to preserve the match data from an earlier search for later use. Here is an example that shows the problem that arises if you fail to save the match data: (re-search-forward "The \\(cat \\)") => 48 (foo) ; Perhaps `foo' does ; more searching. (match-end 0) => 61 ; Unexpected result--not 48! You can save and restore the match data with `save-match-data': - Special Form: save-match-data body... This special form executes BODY, saving and restoring the match data around it. You can use `set-match-data' together with `match-data' to imitate the effect of the special form `save-match-data'. This is useful for writing code that can run in Emacs 18. Here is how: (let ((data (match-data))) (unwind-protect ... ; May change the original match data. (set-match-data data))) Emacs automatically saves and restores the match data when it runs process filter functions (*note Filter Functions::) and process sentinels (*note Sentinels::).  File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching Searching and Case ================== By default, searches in Emacs ignore the case of the text they are searching through; if you specify searching for `FOO', then `Foo' or `foo' is also considered a match. Regexps, and in particular character sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'. If you do not want this feature, set the variable `case-fold-search' to `nil'. Then all letters must match exactly, including case. This is a buffer-local variable; altering the variable affects only the current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you may change the value of `default-case-fold-search', which is the default value of `case-fold-search' for buffers that do not override it. Note that the user-level incremental search feature handles case distinctions differently. When given a lower case letter, it looks for a match of either case, but when given an upper case letter, it looks for an upper case letter only. But this has nothing to do with the searching functions Lisp functions use. - User Option: case-replace This variable determines whether the replacement functions should preserve case. If the variable is `nil', that means to use the replacement text verbatim. A non-`nil' value means to convert the case of the replacement text according to the text being replaced. The function `replace-match' is where this variable actually has its effect. *Note Replacing Match::. - User Option: case-fold-search This buffer-local variable determines whether searches should ignore case. If the variable is `nil' they do not ignore case; otherwise they do ignore case. - Variable: default-case-fold-search The value of this variable is the default value for `case-fold-search' in buffers that do not override it. This is the same as `(default-value 'case-fold-search)'.  File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching Standard Regular Expressions Used in Editing ============================================ This section describes some variables that hold regular expressions used for certain purposes in editing: - Variable: page-delimiter This is the regexp describing line-beginnings that separate pages. The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this matches a line that starts with a formfeed character. The following two regular expressions should _not_ assume the match always starts at the beginning of a line; they should not use `^' to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that `^' would be superfluous. When there is a nonzero left margin, they accept matches that start after the left margin. In that case, a `^' would be incorrect. However, a `^' is harmless in modes where a left margin is never used. - Variable: paragraph-separate This is the regular expression for recognizing the beginning of a line that separates paragraphs. (If you change this, you may have to change `paragraph-start' also.) The default value is `"[ \t\f]*$"', which matches a line that consists entirely of spaces, tabs, and form feeds (after its left margin). - Variable: paragraph-start This is the regular expression for recognizing the beginning of a line that starts _or_ separates paragraphs. The default value is `"[ \t\n\f]"', which matches a line starting with a space, tab, newline, or form feed (after its left margin). - Variable: sentence-end This is the regular expression describing the end of a sentence. (All paragraph boundaries also end sentences, regardless.) The default value is: "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" This means a period, question mark or exclamation mark, followed optionally by a closing parenthetical character, followed by tabs, spaces or new lines. For a detailed explanation of this regular expression, see *Note Regexp Example::.  File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top Syntax Tables ************* A "syntax table" specifies the syntactic textual function of each character. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (*note Word Motion::) and the list motion functions (*note List Motion::) as well as the functions in this chapter. * Menu: * Basics: Syntax Basics. Basic concepts of syntax tables. * Desc: Syntax Descriptors. How characters are classified. * Syntax Table Functions:: How to create, examine and alter syntax tables. * Motion and Syntax:: Moving over characters with certain syntaxes. * Parsing Expressions:: Parsing balanced expressions using the syntax table. * Standard Syntax Tables:: Syntax tables used by various major modes. * Syntax Table Internals:: How syntax table information is stored.  File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables Syntax Table Concepts ===================== A "syntax table" provides Emacs with the information that determines the syntactic use of each character in a buffer. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (*note Word Motion::) and the list motion functions (*note List Motion::) as well as the functions in this chapter. Under XEmacs 20 and later, a syntax table is a particular subtype of the primitive char table type (*note Char Tables::), and each element of the char table is an integer that encodes the syntax of the character in question, or a cons of such an integer and a matching character (for characters with parenthesis syntax). Under XEmacs 19, a syntax table is a vector of 256 elements; it contains one entry for each of the 256 possible characters in an 8-bit byte. Each element is an integer that encodes the syntax of the character in question. (The matching character, if any, is embedded in the bits of this integer.) Syntax tables are used only for moving across text, not for the Emacs Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, XEmacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. Changing this table alters the syntax in all those buffers as well as in any buffers subsequently put in that mode. Occasionally several similar modes share one syntax table. *Note Example Major Modes::, for an example of how to set up a syntax table. A syntax table can inherit the data for some characters from the standard syntax table, while specifying other characters itself. The "inherit" syntax class means "inherit this character's syntax from the standard syntax table." Most major modes' syntax tables inherit the syntax of character codes 0 through 31 and 128 through 255. This is useful with character sets such as ISO Latin-1 that have additional alphabetic characters in the range 128 to 255. Just changing the standard syntax for these characters affects all major modes. - Function: syntax-table-p object This function returns `t' if OBJECT is a vector of length 256 elements. This means that the vector may be a syntax table. However, according to this test, any vector of length 256 is considered to be a syntax table, no matter what its contents.  File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables Syntax Descriptors ================== This section describes the syntax classes and flags that denote the syntax of a character, and how they are represented as a "syntax descriptor", which is a Lisp string that you pass to `modify-syntax-entry' to specify the desired syntax. XEmacs defines a number of "syntax classes". Each syntax table puts each character into one class. There is no necessary relationship between the class of a character in one syntax table and its class in any other table. Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the designator character is one that is frequently in that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. A syntax descriptor is a Lisp string that specifies a syntax class, a matching character (used only for the parenthesis classes) and flags. The first character is the designator for a syntax class. The second character is the character to match; if it is unused, put a space there. Then come the characters for any desired flags. If no matching character or flags are needed, one character is sufficient. For example, the descriptor for the character `*' in C mode is `. 23' (i.e., punctuation, matching character slot unused, second character of a comment-starter, first character of an comment-ender), and the entry for `/' is `. 14' (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender). * Menu: * Syntax Class Table:: Table of syntax classes. * Syntax Flags:: Additional flags each character can have.  File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors Table of Syntax Classes ----------------------- Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use. - Syntax class: whitespace character "Whitespace characters" (designated with `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic significance, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are almost always classified as whitespace. (The designator ` ' is accepted for backwards compatibility with older versions of XEmacs, but is deprecated. It is invalid in GNU Emacs.) - Syntax class: word constituent "Word constituents" (designated with `w') are parts of normal English words and are typically used in variable and command names in programs. All upper- and lower-case letters, and the digits, are typically word constituents. - Syntax class: symbol constituent "Symbol constituents" (designated with `_') are the extra characters that are used in variable and command names along with word constituents. For example, the symbol constituents class is used in Lisp mode to indicate that certain characters may be part of symbol names even though they are not part of English words. These characters are `$&*+-_<>'. In standard C, the only non-word-constituent character that is valid in symbols is underscore (`_'). - Syntax class: punctuation character "Punctuation characters" (`.') are those characters that are used as punctuation in English, or are used in some way in a programming language to separate symbols from one another. Most programming language modes, including Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses. - Syntax class: open parenthesis character - Syntax class: close parenthesis character Open and close "parenthesis characters" are characters used in dissimilar pairs to surround sentences or expressions. Such a grouping is begun with an open parenthesis character and terminated with a close. Each open parenthesis character matches a particular close parenthesis character, and vice versa. Normally, XEmacs indicates momentarily the matching open parenthesis when you insert a close parenthesis. *Note Blinking::. The class of open parentheses is designated with `(', and that of close parentheses with `)'. In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters. - Syntax class: string quote "String quote characters" (designated with `"') are used in many languages, including Lisp and C, to delimit string constants. The same string quote character appears at the beginning and the end of a string. Such quoted strings do not nest. The parsing facilities of XEmacs consider a string as a single token. The usual syntactic meanings of the characters in the string are suppressed. The Lisp modes have two string quote characters: double-quote (`"') and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and single-quote (`'') for character constants. English text has no string quote characters because English is not a programming language. Although quotation marks are used in English, we do not want them to turn off the usual syntactic properties of other characters in the quotation. - Syntax class: escape An "escape character" (designated with `\') starts an escape sequence such as is used in C string and character constants. The character `\' belongs to this class in both C and Lisp. (In C, it is used thus only inside strings, but it turns out to cause no trouble to treat it this way throughout C code.) Characters in this class count as part of words if `words-include-escapes' is non-`nil'. *Note Word Motion::. - Syntax class: character quote A "character quote character" (designated with `/') quotes the following character so that it loses its normal syntactic meaning. This differs from an escape character in that only the character immediately following is ever affected. Characters in this class count as part of words if `words-include-escapes' is non-`nil'. *Note Word Motion::. This class is used for backslash in TeX mode. - Syntax class: paired delimiter "Paired delimiter characters" (designated with `$') are like string quote characters except that the syntactic properties of the characters between the delimiters are not suppressed. Only TeX mode uses a paired delimiter presently--the `$' that both enters and leaves math mode. - Syntax class: expression prefix An "expression prefix operator" (designated with `'') is used for syntactic operators that are part of an expression if they appear next to one. These characters in Lisp include the apostrophe, `'' (used for quoting), the comma, `,' (used in macros), and `#' (used in the read syntax for certain data types). - Syntax class: comment starter - Syntax class: comment ender The "comment starter" and "comment ender" characters are used in various languages to delimit comments. These classes are designated with `<' and `>', respectively. English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one. - Syntax class: inherit This syntax class does not specify a syntax. It says to look in the standard syntax table to find the syntax of this character. The designator for this syntax code is `@'.  File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors Syntax Flags ------------ In addition to the classes, entries for characters in a syntax table can include flags. There are eleven possible flags, represented by the digits `1'-`8', and the lowercase letters `a', `b', and `p'. All the flags except `p' are used to describe comment delimiters. The digit flags indicate that a character can _also_ be part of a multi-character comment sequence, in addition to the syntactic properties associated with its character class. The flags must be independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, _and_ the second character of a start-of-comment sequence (`/*'), _and_ the first character of an end-of-comment sequence (`*/'). Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with the comment-start sequence of style "b", it must also end with the comment-end sequence of style "b". As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary comment-start sequences and two arbitrary comment-end sequences. (Thus the need for 8 flags.) GNU Emacs restricts the comment-start sequences to start with the same character, XEmacs does not. This means that for two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses the digit flags `5'-`8'. A one character comment-end sequence applies to the "b" style if its first character has the `b' flag set; otherwise, it applies to the "a" style. The `a' flag is optional. These flags have no effect on non-comment characters; two-character styles are determined by the digit flags. The flags for a character C are: * `1' means C is the start of a two-character comment-start sequence of style "a". * `2' means C is the second character of such a sequence. * `3' means C is the start of a two-character comment-end sequence of style "a". * `4' means C is the second character of such a sequence. * `5' means C is the start of a two-character comment-start sequence of style "b". * `6' means C is the second character of such a sequence. * `7' means C is the start of a two-character comment-end sequence of style "b". * `8' means C is the second character of such a sequence. * `a' means that C as a comment delimiter belongs to the default "a" comment style. (This flag is optional.) * `b' means that C as a comment delimiter belongs to the alternate "b" comment style. * `p' identifies an additional "prefix character" for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax codes. The function `backward-prefix-chars' moves back over these characters, as well as over characters whose primary syntax class is prefix (`''). *Note Motion and Syntax::. Lisp (as you would expect) has a simple comment syntax. `;' `<' newline `>' Note that no flags are used. This defines two comment-delimiting sequences: `;' This is a single-character comment-start sequence because the syntax class is `<'. newline This is a single character comment-end sequence because the syntax class is `>' and the `b' flag is not set. C++ (again, as you would expect) has a baroque, overrich, and excessively complex comment syntax. `/' `1456' `*' `23' newline `>b' Note that the "b" style mixes one-character and two-character sequences. The table above defines four comment-delimiting sequences: `/*' This is a comment-start sequence for "a" style because the `1' flag is set on `/' and the `2' flag is set on `*'. `//' This is a comment-start sequence for "b" style because both the `5' and the `6' flags are set on `/'. `*/' This is a comment-end sequence for "a" style because the `3' flag is set on `*' and the `4' flag is set on `/'. newline This is a comment-end sequence for "b" style, because the newline character has the `b' flag.  File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables Syntax Table Functions ====================== In this section we describe functions for creating, accessing and altering syntax tables. - Function: make-syntax-table &optional oldtable This function creates a new syntax table. Character codes 0 through 31 and 128 through 255 are set up to inherit from the standard syntax table. The other character codes are set up by copying what the standard syntax table says about them. Most major mode syntax tables are created in this way. - Function: copy-syntax-table &optional syntax-table This function constructs a copy of SYNTAX-TABLE and returns it. If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy of the current syntax table. Otherwise, an error is signaled if SYNTAX-TABLE is not a syntax table. - Command: modify-syntax-entry char-range syntax-descriptor &optional syntax-table This function sets the syntax entry for CHAR-RANGE according to SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a range of characters, as used with `put-char-table'. The syntax is changed only for SYNTAX-TABLE, which defaults to the current buffer's syntax table, and not in any other syntax table. The argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a string beginning with a class designator character, and optionally containing a matching character and flags as well. *Note Syntax Descriptors::. This function always returns `nil'. The old syntax information in the table for CHAR-RANGE is discarded. An error is signaled if the first character of the syntax descriptor is not one of the twelve syntax class designator characters. Examples: ;; Put the space character in class whitespace. (modify-syntax-entry ?\ " ") => nil ;; Make `$' an open parenthesis character, ;; with `^' as its matching close. (modify-syntax-entry ?$ "(^") => nil ;; Make `^' a close parenthesis character, ;; with `$' as its matching open. (modify-syntax-entry ?^ ")$") => nil ;; Make `/' a punctuation character, ;; the first character of a start-comment sequence, ;; and the second character of an end-comment sequence. ;; This is used in C mode. (modify-syntax-entry ?/ ". 14") => nil - Function: char-syntax character &optional syntax-table This function returns the syntax class of CHARACTER, represented by its mnemonic designator character. This _only_ returns the class, not any matching parenthesis or flags. An error is signaled if CHARACTER is not a character. The characters that correspond to various syntax codes are listed in the documentation of `modify-syntax-entry'. Optional second argument SYNTAX-TABLE is the syntax table to be used, and defaults to the current buffer's syntax table. The following examples apply to C mode. The first example shows that the syntax class of space is whitespace (represented by a space). The second example shows that the syntax of `/' is punctuation. This does not show the fact that it is also part of comment-start and -end sequences. The third example shows that open parenthesis is in the class of open parentheses. This does not show the fact that it has a matching character, `)'. (char-to-string (char-syntax ?\ )) => " " (char-to-string (char-syntax ?/)) => "." (char-to-string (char-syntax ?\()) => "(" - Function: set-syntax-table syntax-table &optional buffer This function makes SYNTAX-TABLE the syntax table for BUFFER, which defaults to the current buffer if omitted. It returns SYNTAX-TABLE. - Function: syntax-table &optional buffer This function returns the syntax table for BUFFER, which defaults to the current buffer if omitted.  File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables Motion and Syntax ================= This section describes functions for moving across characters in certain syntax classes. None of these functions exists in Emacs version 18 or earlier. - Function: skip-syntax-forward syntaxes &optional limit buffer This function moves point forward across characters having syntax classes mentioned in SYNTAXES. It stops when it encounters the end of the buffer, or position LIMIT (if specified), or a character it is not supposed to skip. Optional argument BUFFER defaults to the current buffer if omitted. - Function: skip-syntax-backward syntaxes &optional limit buffer This function moves point backward across characters whose syntax classes are mentioned in SYNTAXES. It stops when it encounters the beginning of the buffer, or position LIMIT (if specified), or a character it is not supposed to skip. Optional argument BUFFER defaults to the current buffer if omitted. - Function: backward-prefix-chars &optional buffer This function moves point backward over any number of characters with expression prefix syntax. This includes both characters in the expression prefix syntax class, and characters with the `p' flag. Optional argument BUFFER defaults to the current buffer if omitted.  File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables Parsing Balanced Expressions ============================ Here are several functions for parsing and scanning balanced expressions, also known as "sexps", in which parentheses match in pairs. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. *Note List Motion::, for convenient higher-level functions for moving over balanced expressions. - Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment buffer This function parses a sexp in the current buffer starting at START, not scanning past LIMIT. It stops at position LIMIT or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a value describing the status of the parse at the point where it stops. If STATE is `nil', START is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a STATE argument that describes the initial status of parsing. If the third argument TARGET-DEPTH is non-`nil', parsing stops if the depth in parentheses becomes equal to TARGET-DEPTH. The depth starts at 0, or at whatever is given in STATE. If the fourth argument STOP-BEFORE is non-`nil', parsing stops when it comes to any character that starts a sexp. If STOP-COMMENT is non-`nil', parsing stops when it comes to the start of a comment. The fifth argument STATE is an eight-element list of the same form as the value of this function, described below. The return value of one call may be used to initialize the state of the parse on another call to `parse-partial-sexp'. The result is a list of eight elements describing the final state of the parse: 0. The depth in parentheses, counting from 0. 1. The character position of the start of the innermost parenthetical grouping containing the stopping point; `nil' if none. 2. The character position of the start of the last complete subexpression terminated; `nil' if none. 3. Non-`nil' if inside a string. More precisely, this is the character that will terminate the string. 4. `t' if inside a comment (of either style). 5. `t' if point is just after a quote character. 6. The minimum parenthesis depth encountered during this scan. 7. `t' if inside a comment of style "b". Elements 0, 3, 4, 5 and 7 are significant in the argument STATE. This function is most often used to compute indentation for languages that have nested parentheses. - Function: scan-lists from count depth &optional buffer noerror This function scans forward COUNT balanced parenthetical groupings from character number FROM. It returns the character position where the scan stops. If DEPTH is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; `scan-lists' counts COUNT such places and then stops. Thus, a positive value for DEPTH means go out DEPTH levels of parenthesis. Scanning ignores comments if `parse-sexp-ignore-comments' is non-`nil'. If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, `nil' is returned. If optional arg BUFFER is non-`nil', scanning occurs in that buffer instead of in the current buffer. If optional arg NOERROR is non-`nil', `scan-lists' will return `nil' instead of signalling an error. - Function: scan-sexps from count &optional buffer noerror This function scans forward COUNT sexps from character position FROM. It returns the character position where the scan stops. Scanning ignores comments if `parse-sexp-ignore-comments' is non-`nil'. If the scan reaches the beginning or end of (the accessible part of) the buffer in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, `nil' is returned. If optional arg BUFFER is non-`nil', scanning occurs in that buffer instead of in the current buffer. If optional arg NOERROR is non-`nil', `scan-sexps' will return nil instead of signalling an error. - Variable: parse-sexp-ignore-comments If the value is non-`nil', then comments are treated as whitespace by the functions in this section and by `forward-sexp'. In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable `nil', since not every newline is the end of a comment. This limitation no longer exists. You can use `forward-comment' to move forward or backward over one comment or several comments. - Function: forward-comment &optional count buffer This function moves point forward across COUNT comments (backward, if COUNT is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying COUNT. COUNT defaults to `1'. Optional argument BUFFER defaults to the current buffer. To move forward over all comments and whitespace following point, use `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument to use, because the number of comments in the buffer cannot exceed that many.  File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables Some Standard Syntax Tables =========================== Most of the major modes in XEmacs have their own syntax tables. Here are several of them: - Function: standard-syntax-table This function returns the standard syntax table, which is the syntax table used in Fundamental mode. - Variable: text-mode-syntax-table The value of this variable is the syntax table used in Text mode. - Variable: c-mode-syntax-table The value of this variable is the syntax table for C-mode buffers. - Variable: emacs-lisp-mode-syntax-table The value of this variable is the syntax table used in Emacs Lisp mode by editing commands. (It has no effect on the Lisp `read' function.)  File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables Syntax Table Internals ====================== Each element of a syntax table is an integer that encodes the syntax of one character: the syntax class, possible matching character, and flags. Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (*note Syntax Descriptors::). The low 8 bits of each element of a syntax table indicate the syntax class. Integer Class 0 whitespace 1 punctuation 2 word 3 symbol 4 open parenthesis 5 close parenthesis 6 expression prefix 7 string quote 8 paired delimiter 9 escape 10 character quote 11 comment-start 12 comment-end 13 inherit The next 8 bits are the matching opposite parenthesis (if the character has parenthesis syntax); otherwise, they are not meaningful. The next 6 bits are the flags.  File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top Abbrevs And Abbrev Expansion **************************** An abbreviation or "abbrev" is a string of characters that may be expanded to a longer string. The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev. This saves typing. The set of abbrevs currently in effect is recorded in an "abbrev table". Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used. An abbrev table is represented as an obarray containing a symbol for each abbreviation. The symbol's name is the abbreviation; its value is the expansion; its function definition is the hook function to do the expansion (*note Defining Abbrevs::); its property list cell contains the use count, the number of times the abbreviation has been expanded. Because these symbols are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, normally they are never used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. *Note Creating Symbols::. For the user-level commands for abbrevs, see *Note Abbrev Mode: (xemacs)Abbrevs. * Menu: * Abbrev Mode:: Setting up XEmacs for abbreviation. * Tables: Abbrev Tables. Creating and working with abbrev tables. * Defining Abbrevs:: Specifying abbreviations and their expansions. * Files: Abbrev Files. Saving abbrevs in files. * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. * Standard Abbrev Tables:: Abbrev tables used by various major modes.  File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs Setting Up Abbrev Mode ====================== Abbrev mode is a minor mode controlled by the value of the variable `abbrev-mode'. - Variable: abbrev-mode A non-`nil' value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is `nil', abbrevs may be defined, but they are not expanded automatically. This variable automatically becomes local when set in any fashion. - Variable: default-abbrev-mode This is the value of `abbrev-mode' for buffers that do not override it. This is the same as `(default-value 'abbrev-mode)'.  File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs Abbrev Tables ============= This section describes how to create and manipulate abbrev tables. - Function: make-abbrev-table This function creates and returns a new, empty abbrev table--an obarray containing no symbols. It is a vector filled with zeros. - Function: clear-abbrev-table table This function undefines all the abbrevs in abbrev table TABLE, leaving it empty. The function returns `nil'. - Function: define-abbrev-table table-name definitions This function defines TABLE-NAME (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to DEFINITIONS, a list of elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is always `nil'. - Variable: abbrev-table-name-list This is a list of symbols whose values are abbrev tables. `define-abbrev-table' adds the new abbrev table name to this list. - Function: insert-abbrev-table-description name &optional human This function inserts before point a description of the abbrev table named NAME. The argument NAME is a symbol whose value is an abbrev table. The value is always `nil'. If HUMAN is non-`nil', the description is human-oriented. Otherwise the description is a Lisp expression--a call to `define-abbrev-table' that would define NAME exactly as it is currently defined.  File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs Defining Abbrevs ================ These functions define an abbrev in a specified abbrev table. `define-abbrev' is the low-level basic function, while `add-abbrev' is used by commands that ask for information from the user. - Function: add-abbrev table type arg This function adds an abbreviation to abbrev table TABLE based on information from the user. The argument TYPE is a string describing in English the kind of abbrev this will be (typically, `"global"' or `"mode-specific"'); this is used in prompting the user. The argument ARG is the number of words in the expansion. The return value is the symbol that internally represents the new abbrev, or `nil' if the user declines to confirm redefining an existing abbrev. - Function: define-abbrev table name &optional expansion hook count This function defines an abbrev in TABLE named NAME, to expand to EXPANSION, and call HOOK. The return value is an uninterned symbol that represents the abbrev inside XEmacs; its name is NAME. The argument NAME should be a string. The argument EXPANSION should be a string, or `nil' to undefine the abbrev. The argument HOOK is a function or `nil'. If HOOK is non-`nil', then it is called with no arguments after the abbrev is replaced with EXPANSION; point is located at the end of EXPANSION when HOOK is called. The use count of the abbrev is initialized to zero. - User Option: only-global-abbrevs If this variable is non-`nil', it means that the user plans to use global abbrevs only. This tells the commands that define mode-specific abbrevs to define global ones instead. This variable does not alter the behavior of the functions in this section; it is examined by their callers.  File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs Saving Abbrevs in Files ======================= A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same abbrev tables with the same contents. Therefore, you can load the file with `load' (*note How Programs Do Loading::). However, the function `quietly-read-abbrev-file' is provided as a more convenient interface. User-level facilities such as `save-some-buffers' can save abbrevs in a file automatically, under the control of variables described here. - User Option: abbrev-file-name This is the default file name for reading and saving abbrevs. - Function: quietly-read-abbrev-file &optional filename This function reads abbrev definitions from a file named FILENAME, previously written with `write-abbrev-file'. If FILENAME is `nil', the file specified in `abbrev-file-name' is used. `save-abbrevs' is set to `t' so that changes will be saved. This function does not display any messages. It returns `nil'. - User Option: save-abbrevs A non-`nil' value for `save-abbrev' means that XEmacs should save abbrevs when files are saved. `abbrev-file-name' specifies the file to save the abbrevs in. - Variable: abbrevs-changed This variable is set non-`nil' by defining or altering any abbrevs. This serves as a flag for various XEmacs commands to offer to save your abbrevs. - Command: write-abbrev-file filename Save all abbrev definitions, in all abbrev tables, in the file FILENAME, in the form of a Lisp program that when loaded will define the same abbrevs. This function returns `nil'.  File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs Looking Up and Expanding Abbreviations ====================================== Abbrevs are usually expanded by commands for interactive use, including `self-insert-command'. This section describes the subroutines used in writing such functions, as well as the variables they use for communication. - Function: abbrev-symbol abbrev &optional table This function returns the symbol representing the abbrev named ABBREV. The value returned is `nil' if that abbrev is not defined. The optional second argument TABLE is the abbrev table to look it up in. If TABLE is `nil', this function tries first the current buffer's local abbrev table, and second the global abbrev table. - Function: abbrev-expansion abbrev &optional table This function returns the string that ABBREV would expand into (as defined by the abbrev tables used for the current buffer). The optional argument TABLE specifies the abbrev table to use, as in `abbrev-symbol'. - Command: expand-abbrev This command expands the abbrev before point, if any. If point does not follow an abbrev, this command does nothing. The command returns `t' if it did expansion, `nil' otherwise. - Command: abbrev-prefix-mark &optional arg Mark current point as the beginning of an abbrev. The next call to `expand-abbrev' will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual. - User Option: abbrev-all-caps When this is set non-`nil', an abbrev entered entirely in upper case is expanded using all upper case. Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion. - Variable: abbrev-start-location This is the buffer position for `expand-abbrev' to use as the start of the next abbrev to be expanded. (`nil' means use the word before point instead.) `abbrev-start-location' is set to `nil' each time `expand-abbrev' is called. This variable is also set by `abbrev-prefix-mark'. - Variable: abbrev-start-location-buffer The value of this variable is the buffer for which `abbrev-start-location' has been set. Trying to expand an abbrev in any other buffer clears `abbrev-start-location'. This variable is set by `abbrev-prefix-mark'. - Variable: last-abbrev This is the `abbrev-symbol' of the last abbrev expanded. This information is left by `expand-abbrev' for the sake of the `unexpand-abbrev' command. - Variable: last-abbrev-location This is the location of the last abbrev expanded. This contains information left by `expand-abbrev' for the sake of the `unexpand-abbrev' command. - Variable: last-abbrev-text This is the exact expansion text of the last abbrev expanded, after case conversion (if any). Its value is `nil' if the abbrev has already been unexpanded. This contains information left by `expand-abbrev' for the sake of the `unexpand-abbrev' command. - Variable: pre-abbrev-expand-hook This is a normal hook whose functions are executed, in sequence, just before any expansion of an abbrev. *Note Hooks::. Since it is a normal hook, the hook functions receive no arguments. However, they can find the abbrev to be expanded by looking in the buffer before point. The following sample code shows a simple use of `pre-abbrev-expand-hook'. If the user terminates an abbrev with a punctuation character, the hook function asks for confirmation. Thus, this hook allows the user to decide whether to expand the abbrev, and aborts expansion if it is not confirmed. (add-hook 'pre-abbrev-expand-hook 'query-if-not-space) ;; This is the function invoked by `pre-abbrev-expand-hook'. ;; If the user terminated the abbrev with a space, the function does ;; nothing (that is, it returns so that the abbrev can expand). If the ;; user entered some other character, this function asks whether ;; expansion should continue. ;; If the user answers the prompt with `y', the function returns ;; `nil' (because of the `not' function), but that is ;; acceptable; the return value has no effect on expansion. (defun query-if-not-space () (if (/= ?\ (preceding-char)) (if (not (y-or-n-p "Do you want to expand this abbrev? ")) (error "Not expanding this abbrev"))))  File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs Standard Abbrev Tables ====================== Here we list the variables that hold the abbrev tables for the preloaded major modes of XEmacs. - Variable: global-abbrev-table This is the abbrev table for mode-independent abbrevs. The abbrevs defined in it apply to all buffers. Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table. - Variable: local-abbrev-table The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer. - Variable: fundamental-mode-abbrev-table This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode. - Variable: text-mode-abbrev-table This is the local abbrev table used in Text mode. - Variable: c-mode-abbrev-table This is the local abbrev table used in C mode. - Variable: lisp-mode-abbrev-table This is the local abbrev table used in Lisp mode and Emacs Lisp mode.  File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top Extents ******* An "extent" is a region of text (a start position and an end position) that is displayed in a particular face and can have certain other properties such as being read-only. Extents can overlap each other. XEmacs efficiently handles buffers with large numbers of extents in them. - Function: extentp object This returns `t' if OBJECT is an extent. * Menu: * Intro to Extents:: Extents are regions over a buffer or string. * Creating and Modifying Extents:: Basic extent functions. * Extent Endpoints:: Accessing and setting the bounds of an extent. * Finding Extents:: Determining which extents are in an object. * Mapping Over Extents:: More sophisticated functions for extent scanning. * Extent Properties:: Extents have built-in and user-definable properties. * Detached Extents:: Extents that are not in a buffer. * Extent Parents:: Inheriting properties from another extent. * Duplicable Extents:: Extents can be marked to be copied into strings. * Extents and Events:: Extents can interact with the keyboard and mouse. * Atomic Extents:: Treating a block of text as a single entity.  File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents Introduction to Extents ======================= An extent is a region of text within a buffer or string that has certain properties associated with it. The properties of an extent primarily affect the way the text contained in the extent is displayed. Extents can freely overlap each other in a buffer or string. Extents are invisible to functions that merely examine the text of a buffer or string. _Please note:_ An alternative way to add properties to a buffer or string is to use text properties. *Note Text Properties::. An extent is logically a Lisp object consisting of a start position, an end position, a buffer or string to which these positions refer, and a property list. As text is inserted into a buffer, the start and end positions of the extent are automatically adjusted as necessary to keep the extent referring to the same text in the buffer. If text is inserted at the boundary of an extent, the extent's `start-open' and `end-open' properties control whether the text is included as part of the extent. If the text bounded by an extent is deleted, the extent becomes "detached"; its start and end positions are no longer meaningful, but it maintains all its other properties and can later be reinserted into a buffer. (None of these considerations apply to strings, because text cannot be inserted into or deleted from a string.) Each extent has a face or list of faces associated with it, which controls the way in which the text bounded by the extent is displayed. If an extent's face is `nil' or its properties are partially undefined, the corresponding properties from the default face for the frame is used. If two or more extents overlap, or if a list of more than one face is specified for a particular extent, the corresponding faces are merged to determine the text's displayed properties. Every extent has a "priority" that determines which face takes precedence if the faces conflict. (If two extents have the same priority, the one that comes later in the display order takes precedence. *Note display order: Extent Endpoints.) Higher-numbered priority values correspond to a higher priority, and priority values can be negative. Every extent is created with a priority of 0, but this can be changed with `set-extent-priority'. Within a single extent with a list of faces, faces earlier in the list have a higher priority than faces later in the list. Extents can be set to respond specially to key and mouse events within the extent. An extent's `keymap' property controls the effect of key and mouse strokes within the extent's text, and the `mouse-face' property controls whether the extent is highlighted when the mouse moves over it. *Note Extents and Events::. An extent can optionally have a "begin-glyph" or "end-glyph" associated with it. A begin-glyph or end-glyph is a pixmap or string that will be displayed either at the start or end of an extent or in the margin of the line that the start or end of the extent lies in, depending on the extent's layout policy. Begin-glyphs and end-glyphs are used to implement annotations, and you should use the annotation API functions in preference to the lower-level extent functions. For more information, *Note Annotations::. If an extent has its `detachable' property set, it will become "detached" (i.e. no longer in the buffer) when all its text is deleted. Otherwise, it will simply shrink down to zero-length and sit in the same place in the buffer. By default, the `detachable' property is set on newly-created extents. *Note Detached Extents::. If an extent has its `duplicable' property set, it will be remembered when a string is created from text bounded by the extent. When the string is re-inserted into a buffer, the extent will also be re-inserted. This mechanism is used in the kill, yank, and undo commands. *Note Duplicable Extents::.  File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents Creating and Modifying Extents ============================== - Function: make-extent from to &optional buffer-or-string This function makes an extent for the range [FROM, TO) in BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults to the current buffer. Insertions at point TO will be outside of the extent; insertions at FROM will be inside the extent, causing the extent to grow (*note Extent Endpoints::). This is the same way that markers behave. The extent is initially detached if both FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults to `nil', meaning the extent is in no buffer or string (*note Detached Extents::). - Function: delete-extent extent This function removes EXTENT from its buffer and destroys it. This does not modify the buffer's text, only its display properties. The extent cannot be used thereafter. To remove an extent in such a way that it can be re-inserted later, use `detach-extent'. *Note Detached Extents::. - Function: extent-object extent This function returns the buffer or string that EXTENT is in. If the return value is `nil', this means that the extent is detached; however, a detached extent will not necessarily return a value of `nil'. - Function: extent-live-p object This function returns `t' if OBJECT is an extent that has not been deleted, and `nil' otherwise.  File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents Extent Endpoints ================ Every extent has a start position and an end position, and logically affects the characters between those positions. Normally the start and end positions must both be valid positions in the extent's buffer or string. However, both endpoints can be `nil', meaning the extent is detached. *Note Detached Extents::. Whether the extent overlaps its endpoints is governed by its `start-open' and `end-open' properties. Insertion of a character at a closed endpoint will expand the extent to include that character; insertion at an open endpoint will not. Similarly, functions such as `extent-at' that scan over all extents overlapping a particular position will include extents with a closed endpoint at that position, but not extents with an open endpoint. Note that the `start-closed' and `end-closed' properties are equivalent to `start-open' and `end-open' with the opposite sense. Both endpoints can be equal, in which case the extent includes no characters but still exists in the buffer or string. Zero-length extents are used to represent annotations (*note Annotations::) and can be used as a more powerful form of a marker. Deletion of all the characters in an extent may or may not result in a zero-length extent; this depends on the `detachable' property (*note Detached Extents::). Insertion at the position of a zero-length extent expands the extent if both endpoints are closed; goes before the extent if it has the `start-open' property; and goes after the extent if it has the `end-open' property. Zero-length extents with both the `start-open' and `end-open' properties are treated as if their starting point were closed. Deletion of a character on a side of a zero-length extent whose corresponding endpoint is closed causes the extent to be detached if its `detachable' property is set; if the corresponding endpoint is open, the extent remains in the buffer, moving as necessary. Extents are ordered within a buffer or string by increasing start position, and then by decreasing end position (this is called the "display order"). - Function: extent-start-position extent This function returns the start position of EXTENT. - Function: extent-end-position extent This function returns the end position of EXTENT. - Function: extent-length extent This function returns the length of EXTENT in characters. If the extent is detached, this returns `0'. If the extent is not detached, this is equivalent to (- (extent-end-position EXTENT) (extent-start-position EXTENT)) - Function: set-extent-endpoints extent start end &optional buffer-or-string This function sets the start and end position of EXTENT to START and END. If both are `nil', this is equivalent to `detach-extent'. BUFFER-OR-STRING specifies the new buffer or string that the extent should be in, and defaults to EXTENT's buffer or string. (If `nil', and EXTENT is in no buffer and no string, it defaults to the current buffer.) See documentation on `detach-extent' for a discussion of undo recording.  File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents Finding Extents =============== The following functions provide a simple way of determining the extents in a buffer or string. A number of more sophisticated primitives for mapping over the extents in a range of a buffer or string are also provided (*note Mapping Over Extents::). When reading through this section, keep in mind the way that extents are ordered (*note Extent Endpoints::). - Function: extent-list &optional buffer-or-string from to flags property value This function returns a list of the extents in BUFFER-OR-STRING. BUFFER-OR-STRING defaults to the current buffer if omitted. FROM and TO can be used to limit the range over which extents are returned; if omitted, all extents in the buffer or string are returned. More specifically, if a range is specified using FROM and TO, only extents that overlap the range (i.e. begin or end inside of the range) are included in the list. FROM and TO default to the beginning and end of BUFFER-OR-STRING, respectively. FLAGS controls how end cases are treated. For a discussion of this, and exactly what "overlap" means, see `map-extents'. The optional arguments PROPERTY and VALUE can be used to further restrict which extents are returned. They have the same meaning as for `map-extents'. If you want to map a function over the extents in a buffer or string, consider using `map-extents' or `mapcar-extents' instead. See also the function `extents-at'. Functions that create extents must be prepared for the possibility that there are other extents in the same area, created by other functions. To deal with this, functions typically mark their own extents by setting a particular property on them. The following function makes it easier to locate those extents. - Function: extent-at pos &optional object property before at-flag This function finds the "smallest" extent (i.e., the last one in the display order) at (i.e., overlapping) POS in OBJECT (a buffer or string) having PROPERTY set. OBJECT defaults to the current buffer. PROPERTY defaults to `nil', meaning that any extent will do. Returns `nil' if there is no matching extent at POS. If the fourth argument BEFORE is not `nil', it must be an extent; any returned extent will precede that extent. This feature allows `extent-at' to be used by a loop over extents. AT-FLAG controls how end cases are handled (i.e. what "at" really means), and should be one of: `nil' `after' An extent is at POS if it covers the character after POS. This is consistent with the way that text properties work. `before' An extent is at POS if it covers the character before POS. `at' An extent is at POS if it overlaps or abuts POS. This includes all zero-length extents at POS. Note that in all cases, the start-openness and end-openness of the extents considered is ignored. If you want to pay attention to those properties, you should use `map-extents', which gives you more control. The following low-level functions are provided for explicitly traversing the extents in a buffer according to the display order. These functions are mostly intended for debugging--in normal operation, you should probably use `mapcar-extents' or `map-extents', or loop using the BEFORE argument to `extent-at', rather than creating a loop using `next-extent'. - Function: next-extent extent Given an extent EXTENT, this function returns the next extent in the buffer or string's display order. If EXTENT is a buffer or string, this returns the first extent in the buffer or string. - Function: previous-extent extent Given an extent EXTENT, this function returns the previous extent in the buffer or string's display order. If EXTENT is a buffer or string, this returns the last extent in the buffer or string.  File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents Mapping Over Extents ==================== The most basic and general function for mapping over extents is called `map-extents'. You should read through the definition of this function to familiarize yourself with the concepts and optional arguments involved. However, in practice you may find it more convenient to use the function `mapcar-extents' or to create a loop using the `before' argument to `extent-at' (*note Finding Extents::). - Function: map-extents function &optional object from to maparg flags property value This function maps FUNCTION over the extents which overlap a region in OBJECT. OBJECT is normally a buffer or string but could be an extent (see below). The region is normally bounded by [FROM, TO) (i.e. the beginning of the region is closed and the end of the region is open), but this can be changed with the FLAGS argument (see below for a complete discussion). FUNCTION is called with the arguments (extent, MAPARG). The arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and default to the current buffer, the beginning of OBJECT, the end of OBJECT, `nil', and `nil', respectively. `map-extents' returns the first non-`nil' result produced by FUNCTION, and no more calls to FUNCTION are made after it returns non-`nil'. If OBJECT is an extent, FROM and TO default to the extent's endpoints, and the mapping omits that extent and its predecessors. This feature supports restarting a loop based on `map-extents'. Note: OBJECT must be attached to a buffer or string, and the mapping is done over that buffer or string. An extent overlaps the region if there is any point in the extent that is also in the region. (For the purpose of overlap, zero-length extents and regions are treated as closed on both ends regardless of their endpoints' specified open/closedness.) Note that the endpoints of an extent or region are considered to be in that extent or region if and only if the corresponding end is closed. For example, the extent [5,7] overlaps the region [2,5] because 5 is in both the extent and the region. However, (5,7] does not overlap [2,5] because 5 is not in the extent, and neither [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the region. The optional FLAGS can be a symbol or a list of one or more symbols, modifying the behavior of `map-extents'. Allowed symbols are: `end-closed' The region's end is closed. `start-open' The region's start is open. `all-extents-closed' Treat all extents as closed on both ends for the purpose of determining whether they overlap the region, irrespective of their actual open- or closedness. `all-extents-open' Treat all extents as open on both ends. `all-extents-closed-open' Treat all extents as start-closed, end-open. `all-extents-open-closed' Treat all extents as start-open, end-closed. `start-in-region' In addition to the above conditions for extent overlap, the extent's start position must lie within the specified region. Note that, for this condition, open start positions are treated as if 0.5 was added to the endpoint's value, and open end positions are treated as if 0.5 was subtracted from the endpoint's value. `end-in-region' The extent's end position must lie within the region. `start-and-end-in-region' Both the extent's start and end positions must lie within the region. `start-or-end-in-region' Either the extent's start or end position must lie within the region. `negate-in-region' The condition specified by a `*-in-region' flag must _not_ hold for the extent to be considered. At most one of `all-extents-closed', `all-extents-open', `all-extents-closed-open', and `all-extents-open-closed' may be specified. At most one of `start-in-region', `end-in-region', `start-and-end-in-region', and `start-or-end-in-region' may be specified. If optional arg PROPERTY is non-`nil', only extents with that property set on them will be visited. If optional arg VALUE is non-`nil', only extents whose value for that property is `eq' to VALUE will be visited. If you want to map over extents and accumulate a list of results, the following function may be more convenient than `map-extents'. - Function: mapcar-extents function &optional predicate buffer-or-string from to flags property value This function applies FUNCTION to all extents which overlap a region in BUFFER-OR-STRING. The region is delimited by FROM and TO. FUNCTION is called with one argument, the extent. A list of the values returned by FUNCTION is returned. An optional PREDICATE may be used to further limit the extents over which FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and VALUE may also be used to control the extents passed to PREDICATE or FUNCTION, and have the same meaning as in `map-extents'. - Function: map-extent-children function &optional object from to maparg flags property value This function is similar to `map-extents', but differs in that: * It only visits extents which start in the given region. * After visiting an extent E, it skips all other extents which start inside E but end before E's end. Thus, this function may be used to walk a tree of extents in a buffer: (defun walk-extents (buffer &optional ignore) (map-extent-children 'walk-extents buffer)) - Function: extent-in-region-p extent &optional from to flags This function returns `t' if `map-extents' would visit EXTENT if called with the given arguments.  File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents Properties of Extents ===================== Each extent has a property list associating property names with values. Some property names have predefined meanings, and can usually only assume particular values. Assigning other values to such a property either cause the value to be converted into a legal value (e.g., assigning anything but `nil' to a Boolean property will cause the value of `t' to be assigned to the property) or will cause an error. Property names without predefined meanings can be assigned any value. An undefined property is equivalent to a property with a value of `nil', or with a particular default value in the case of properties with predefined meanings. Note that, when an extent is created, the `end-open' and `detachable' properties are set on it. If an extent has a parent, all of its properties actually derive from that parent (or from the root ancestor if the parent in turn has a parent), and setting a property of the extent actually sets that property on the parent. *Note Extent Parents::. - Function: extent-property extent property &optional default This function returns EXTENT's value for PROPERTY, or DEFAULT if no such property exists. - Function: extent-properties extent This function returns a list of all of EXTENT's properties that do not have the value of `nil' (or the default value, for properties with predefined meanings). - Function: set-extent-property extent property value This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a predefined meaning, only certain values are allowed, and some values may be converted to others before being stored.) - Function: set-extent-properties extent plist Change some properties of EXTENT. PLIST is a property list. This is useful to change many extent properties at once. The following table lists the properties with predefined meanings, along with their allowable values. `detached' (Boolean) Whether the extent is detached. Setting this is the same as calling `detach-extent'. *Note Detached Extents::. `destroyed' (Boolean) Whether the extent has been deleted. Setting this is the same as calling `delete-extent'. `priority' (integer) The extent's redisplay priority. Defaults to 0. *Note priority: Intro to Extents. This property can also be set with `set-extent-priority' and accessed with `extent-priority'. `start-open' (Boolean) Whether the start position of the extent is open, meaning that characters inserted at that position go outside of the extent. *Note Extent Endpoints::. `start-closed' (Boolean) Same as `start-open' but with the opposite sense. Setting this property clears `start-open' and vice-versa. `end-open' (Boolean) Whether the end position of the extent is open, meaning that characters inserted at that position go outside of the extent. This is `t' by default. *Note Extent Endpoints::. `end-closed' (Boolean) Same as `end-open' but with the opposite sense. Setting this property clears `end-open' and vice-versa. `read-only' (Boolean) Whether text within this extent will be unmodifiable. `face' (face, face name, list of faces or face names, or `nil') The face in which to display the extent's text. This property can also be set with `set-extent-face' and accessed with `extent-face'. Note that if a list of faces is specified, the faces are merged together, with faces earlier in the list having priority over faces later in the list. `mouse-face' (face, face name, list of faces or face names, or `nil') The face used to display the extent when the mouse moves over it. This property can also be set with `set-extent-mouse-face' and accessed with `extent-mouse-face'. Note that if a list of faces is specified, the faces are merged together, with faces earlier in the list having priority over faces later in the list. *Note Extents and Events::. `pointer' (pointer glyph) The glyph used as the pointer when the mouse moves over the extent. This takes precedence over the `text-pointer-glyph' and `nontext-pointer-glyph' variables. If for any reason this glyph is an invalid pointer, the standard glyphs will be used as fallbacks. *Note Mouse Pointer::. `detachable' (Boolean) Whether this extent becomes detached when all of the text it covers is deleted. This is `t' by default. *Note Detached Extents::. `duplicable' (Boolean) Whether this extent should be copied into strings, so that kill, yank, and undo commands will restore or copy it. *Note Duplicable Extents::. `unique' (Boolean) Meaningful only in conjunction with `duplicable'. When this is set, there may be only one instance of this extent attached at a time. *Note Duplicable Extents::. `invisible' (Boolean) If `t', text under this extent will not be displayed - it will look as if the text and the begin-glyph is not there at all. The end-glyph will still be displayed. `keymap' (keymap or `nil') This keymap is consulted for mouse clicks on this extent or keypresses made while `point' is within the extent. *Note Extents and Events::. `copy-function' This is a hook that is run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). *Note Duplicable Extents::. `paste-function' This is a hook that is run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. *Note Duplicable Extents::. `begin-glyph' (glyph or `nil') This extent's begin glyph. *Note Annotations::. `end-glyph' (glyph or `nil') This extent's end glyph. *Note Annotations::. `begin-glyph-layout' (`text', `whitespace', `inside-margin', or `outside-margin') The layout policy for this extent's begin glyph. Defaults to `text'. *Note Annotations::. `end-glyph-layout' (`text', `whitespace', `inside-margin', or `outside-margin') The layout policy for this extent's end glyph. Defaults to `text'. *Note Annotations::. `initial-redisplay-function' (any funcallable object) The function to be called the first time (a part of) the extent is redisplayed. It will be called with the extent as its argument. This is used by `lazy-shot' to implement lazy font-locking. The functionality is still experimental, and may change without further notice. The following convenience functions are provided for accessing particular properties of an extent. - Function: extent-face extent This function returns the `face' property of EXTENT. This might also return a list of face names. Do not modify this list directly! Instead, use `set-extent-face'. Note that you can use `eq' to compare lists of faces as returned by `extent-face'. In other words, if you set the face of two different extents to two lists that are `equal' but not `eq', then the return value of `extent-face' on the two extents will return the identical list. - Function: extent-mouse-face extent This function returns the `mouse-face' property of EXTENT. This might also return a list of face names. Do not modify this list directly! Instead, use `set-extent-mouse-face'. Note that you can use `eq' to compare lists of faces as returned by `extent-mouse-face', just like for `extent-face'. - Function: extent-priority extent This function returns the `priority' property of EXTENT. - Function: extent-keymap extent This function returns the `keymap' property of EXTENT. - Function: extent-begin-glyph-layout extent This function returns the `begin-glyph-layout' property of EXTENT, i.e. the layout policy associated with the EXTENT's begin glyph. - Function: extent-end-glyph-layout extent This function returns the `end-glyph-layout' property of EXTENT, i.e. the layout policy associated with the EXTENT's end glyph. - Function: extent-begin-glyph extent This function returns the `begin-glyph' property of EXTENT, i.e. the glyph object displayed at the beginning of EXTENT. If there is none, `nil' is returned. - Function: extent-end-glyph extent This function returns the `end-glyph' property of EXTENT, i.e. the glyph object displayed at the end of EXTENT. If there is none, `nil' is returned. The following convenience functions are provided for setting particular properties of an extent. - Function: set-extent-priority extent priority This function sets the `priority' property of EXTENT to PRIORITY. - Function: set-extent-face extent face This function sets the `face' property of EXTENT to FACE. - Function: set-extent-mouse-face extent face This function sets the `mouse-face' property of EXTENT to FACE. - Function: set-extent-keymap extent keymap This function sets the `keymap' property of EXTENT to KEYMAP. KEYMAP must be either a keymap object, or `nil'. - Function: set-extent-begin-glyph-layout extent layout This function sets the `begin-glyph-layout' property of EXTENT to LAYOUT. - Function: set-extent-end-glyph-layout extent layout This function sets the `end-glyph-layout' property of EXTENT to LAYOUT. - Function: set-extent-begin-glyph extent begin-glyph &optional layout This function sets the `begin-glyph' and `glyph-layout' properties of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT defaults to `text' if not specified.) - Function: set-extent-end-glyph extent end-glyph &optional layout This function sets the `end-glyph' and `glyph-layout' properties of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults to `text' if not specified.) - Function: set-extent-initial-redisplay-function extent function This function sets the `initial-redisplay-function' property of the extent to FUNCTION.  File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents Detached Extents ================ A detached extent is an extent that is not attached to a buffer or string but can be re-inserted. Detached extents have a start position and end position of `nil'. Extents can be explicitly detached using `detach-extent'. An extent is also detached when all of its characters are all killed by a deletion, if its `detachable' property is set; if this property is not set, the extent becomes a zero-length extent. (Zero-length extents with the `detachable' property set behave specially. *Note zero-length extents: Extent Endpoints.) - Function: detach-extent extent This function detaches EXTENT from its buffer or string. If EXTENT has the `duplicable' property, its detachment is tracked by the undo mechanism. *Note Duplicable Extents::. - Function: extent-detached-p extent This function returns `nil' if EXTENT is detached, and `t' otherwise. - Function: copy-extent extent &optional object This function makes a copy of EXTENT. It is initially detached. Optional argument OBJECT defaults to EXTENT's object (normally a buffer or string, but could be `nil'). - Function: insert-extent extent &optional start end no-hooks object This function inserts EXTENT from START to END in OBJECT (a buffer or string). If EXTENT is detached from a different buffer or string, or in most cases when EXTENT is already attached, the extent will first be copied as if with `copy-extent'. This function operates the same as if `insert' were called on a string whose extent data calls for EXTENT to be inserted, except that if NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be invoked. *Note Duplicable Extents::.  File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents Extent Parents ============== An extent can have a parent extent set for it. If this is the case, the extent derives all its properties from that extent and has no properties of its own. The only "properties" that the extent keeps are the buffer or string it refers to and the start and end points. (More correctly, the extent's own properties are shadowed. If you later change the extent to have no parent, its own properties will become visible again.) It is possible for an extent's parent to itself have a parent, and so on. Through this, a whole tree of extents can be created, all deriving their properties from one root extent. Note, however, that you cannot create an inheritance loop--this is explicitly disallowed. Parent extents are used to implement the extents over the modeline. - Function: set-extent-parent extent parent This function sets the parent of EXTENT to PARENT. If PARENT is `nil', the extent is set to have no parent. - Function: extent-parent extent This function return the parents (if any) of EXTENT, or `nil'. - Function: extent-children extent This function returns a list of the children (if any) of EXTENT. The children of an extent are all those extents whose parent is that extent. This function does not recursively trace children of children. - Function: extent-descendants extent This function returns a list of all descendants of EXTENT, including EXTENT. This recursively applies `extent-children' to any children of EXTENT, until no more children can be found.  File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents Duplicable Extents ================== If an extent has the `duplicable' property, it will be copied into strings, so that kill, yank, and undo commands will restore or copy it. Specifically: * When a string is created using `buffer-substring' or `buffer-string', any duplicable extents in the region corresponding to the string will be copied into the string (*note Buffer Contents::). When the string is inserted into a buffer using `insert', `insert-before-markers', `insert-buffer' or `insert-buffer-substring', the extents in the string will be copied back into the buffer (*note Insertion::). The extents in a string can, of course, be retrieved explicitly using the standard extent primitives over the string. * Similarly, when text is copied or cut into the kill ring, any duplicable extents will be remembered and reinserted later when the text is pasted back into a buffer. * When `concat' is called on strings, the extents in the strings are copied into the resulting string. * When `substring' is called on a string, the relevant extents are copied into the resulting string. * When a duplicable extent is detached by `detach-extent' or string deletion, or inserted by `insert-extent' or string insertion, the action is recorded by the undo mechanism so that it can be undone later. Note that if an extent gets detached and then a later undo causes the extent to get reinserted, the new extent will not be `eq' to the original extent. * Extent motion, face changes, and attachment via `make-extent' are not recorded by the undo mechanism. This means that extent changes which are to be undo-able must be performed by character editing, or by insertion and detachment of duplicable extents. * A duplicable extent's `copy-function' property, if non-`nil', should be a function, and will be run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). It is called with three arguments: the extent and the buffer positions within it which are being copied. If this function returns `nil', then the extent will not be copied; otherwise it will. * A duplicable extent's `paste-function' property, if non-`nil', should be a function, and will be run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. It is called with three arguments: the original extent and the buffer positions which the copied extent will occupy. (This hook is run after the corresponding text has already been inserted into the buffer.) Note that the extent argument may be detached when this function is run. If this function returns `nil', no extent will be inserted. Otherwise, there will be an extent covering the range in question. Note: if the extent to be copied is already attached to the buffer and overlaps the new range, the extent will simply be extended and the `paste-function' will not be called.  File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents Interaction of Extents with Keyboard and Mouse Events ===================================================== If an extent has the `mouse-face' property set, it will be highlighted when the mouse passes over it. This includes the begin-glyph, but not the end-glyph. Highlighting is accomplished by merging the extent's face with the face or faces specified by the `mouse-face' property. The effect is as if a pseudo-extent with the `mouse-face' face were inserted after the extent in the display order (*note Extent Endpoints::, display order). - Variable: mouse-highlight-priority This variable holds the priority to use when merging in the highlighting pseudo-extent. The default is 1000. This is purposely set very high so that the highlighting pseudo-extent shows up even if there are other extents with various priorities at the same location. You can also explicitly cause an extent to be highlighted. Only one extent at a time can be highlighted in this fashion, and any other highlighted extent will be de-highlighted. - Function: highlight-extent extent &optional highlight-p This function highlights (if HIGHLIGHT-P is non-`nil') or de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the `mouse-face' property. (Nothing happens if EXTENT does not have the `mouse-face' property.) - Function: force-highlight-extent extent &optional highlight-p This function is similar to `highlight-extent' but highlights or de-highlights the extent regardless of whether it has the `mouse-face' property. If an extent has a `keymap' property, this keymap will be consulted for mouse clicks on the extent and keypresses made while `point' is within the extent. The behavior of mouse clicks and keystrokes not defined in the keymap is as normal for the buffer.  File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents Atomic Extents ============== If the Lisp file `atomic-extents' is loaded, then the atomic extent facility is available. An "atomic extent" is an extent for which `point' cannot be positioned anywhere within it. This ensures that when selecting text, either all or none of the extent is selected. To make an extent atomic, set its `atomic' property.  File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top Specifiers ********** A specifier is an object used to keep track of a property whose value should vary according to _display context_, a window, a frame, or device. The value of many built-in properties, such as the font, foreground, background, and such properties of a face and variables such as `modeline-shadow-thickness' and `top-toolbar-height', is actually a specifier object. The specifier object, in turn, is "instanced" in a particular situation to yield the real value of the property in the current context. - Function: specifierp object This function returns non-`nil' if OBJECT is a specifier. * Menu: * Introduction to Specifiers:: Specifiers provide a clean way for display and other properties to vary (under user control) in a wide variety of contexts. * Simple Specifier Usage:: Getting started with specifiers. * Specifiers In-Depth:: Gory details about specifier innards. * Specifier Instancing:: Instancing means obtaining the ``value'' of a specifier in a particular context. * Specifier Types:: Specifiers come in different flavors. * Adding Specifications:: Specifications control a specifier's ``value'' by giving conditions under which a particular value is valid. * Retrieving Specifications:: Querying a specifier's specifications. * Specifier Tag Functions:: Working with specifier tags. * Specifier Instancing Functions:: Functions to instance a specifier. * Specifier Examples:: Making all this stuff clearer. * Creating Specifiers:: Creating specifiers for your own use. * Specifier Validation Functions:: Validating the components of a specifier. * Other Specification Functions:: Other ways of working with specifications.  File: lispref.info, Node: Introduction to Specifiers, Next: Simple Specifier Usage, Up: Specifiers Introduction to Specifiers ========================== Perhaps the most useful way to explain specifiers is via an analogy. Emacs Lisp programmers are used to _buffer-local variables_ *Note Buffer-Local Variables::. For example, the variable `modeline-format', which controls the format of the modeline, can have different values depending on the particular buffer being edited. The variable has a default value which most modes will use, but a specialized package such as Calendar might change the variable so as to tailor the modeline to its own purposes. Other variables are perhaps best thought of as "mode local," such as font-lock keywords, but they are implemented as buffer locals. Other properties (such as those that can be changed by the `modify-frame-parameters' function, for example the color of the text cursor) can have frame-local values, although it might also make sense for them to have buffer-local values. In other cases, you might want the property to vary depending on the particular window within the frame that applies (e.g. the top or bottom window in a split frame), the device type that that frame appears on (X or tty), etc. Perhaps you can envision some more complicated scenario where you want a particular value in a specified buffer, another value in all other buffers displayed on a particular frame, another value in all other buffers displayed in all other frames on any mono (two-color, e.g. black and white only) displays, and a default value in all other circumstances. Specifiers generalize both buffer- and frame-local properties. Specifiers vary according to the _display_ context. Font-lock keywords in a buffer will be the same no matter which window the buffer is displayed in, but windows on TTY devices will simply not be capable of the flexibility that windows on modern GUI devices are. Specifiers provide a way for the programmer to _declare_ that an emphasized text should be italic on GUI devices and inverse video on TTYs. They also provide a way for the programmer to declare fallbacks, so that a color specified as "chartreuse" where possible can fall back to "yellow" on devices where only ANSI (4-bit) color is available. The complex calculations and device querying are transparent to both user and programmer. You ask for what you want; it's up to XEmacs to provide it, or a reasonable approximation. We call such a declaration a "specification". A "specification" applies in a particular "locale", which is a window, buffer, frame, device, or the global locale. The value part of the specification is called an "instantiator". The process of determining the value in a particular context, or "domain", is called "instantiation" or "instancing". A domain is a window, frame, or device. The difference between "locale" and "domain" is somewhat subtle. You may think of a locale as a class of domains, which may span different devices. Since the specification is abstract (a Lisp form), you can state it without reference to a device. On the other hand, when you instantiate a specification, you must know the type of the device. It is useless to specify that "blue means emphasis" on a monochrome device. Thus instantiation requires specification of the device on which it will be rendered. Thus a "specifier" allows a great deal of flexibility in controlling exactly what value a property has in which circumstances. Specifiers are most commonly used for display properties, such as an image or the foreground color of a face. As a simple example, you can specify that the foreground of the default face be * blue for a particular buffer * green for all other buffers As a more complicated example, you could specify that the foreground of the default face be * forest green for all buffers displayed in a particular Emacs window, or green if the X server doesn't recognize the color `forest green' * blue for all buffers displayed in a particular frame * red for all other buffers displayed on a color device * white for all other buffers  File: lispref.info, Node: Simple Specifier Usage, Next: Specifiers In-Depth, Prev: Introduction to Specifiers, Up: Specifiers Simple Specifier Usage ====================== A useful specifier application is adding a button to a toolbar. XEmacs provides several toolbars, one along each edge of the frame. Normally only one is used at a time, the default. The default toolbar is actually a specifier object which is the value of `default-toolbar'. *Note Toolbar Intro::. The specification of a toolbar is simple: it is a list of buttons. Each button is a vector with four elements: an icon, a command, the enabled flag, and a help string. Let's retrieve the instance of the toolbar you see in the selected frame. (specifier-instance default-toolbar) The value returned is, as promised, a list of vectors. Now let's build up a button, and add it to the toolbar. Our button will invoke the last defined keyboard macro. This is an alternative to `name-last-kbd-macro' for creating a persistent macro, rather than an alias for `C-x e'. A toolbar button icon can be quite sophisticated, with different images for button up, button down, and disabled states, and a similar set with captions. We'll use a very simple icon, but we have to jump through a few non-obvious hoops designed to support the sophisticated applications. The rest of the button descriptor is straightforward. (setq toolbar-my-kbd-macro-button `[ (list (make-glyph "MyKbdMac")) (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) t "Execute a previously defined keyboard macro." ]) (set-specifier default-toolbar (cons toolbar-my-kbd-macro-button (specifier-specs default-toolbar 'global)) 'global) To remove the button, just substitute the function `delete' for the `cons' above. What is the difference between `specifier-instance', which we used in the example of retrieving the toolbar descriptor, and `specifier-specs', which was used in the toolbar manipulating code? `specifier-specs' retrieves a copy of the instantiator, which is abstract and does not depend on context. `specifier-instance', on the other hand, actually instantiates the specification, and returns the result for the given context. Another way to express this is: `specifier-specs' takes a _locale_ as an argument, while `specifier-instance' takes a _domain_. The reason for providing `specifier-instance' is that sometimes you wish to see the object that XEmacs will actually use. `specifier-specs', on the other hand, shows you what the programmer (or user) requested. When a program manipulates specifications, clearly it's the latter that is desirable. In the case of the toolbar descriptor, it turns out that these are the same: the instancing process is trivial. However, many specifications have non-trivial instancing. Compare the results of the following forms on my system. (The `(cdr (first ...))' form is due to my use of Mule. On non-Mule XEmacsen, just use `specifier-specs'.) (cdr (first (specifier-specs (face-font 'default) 'global))) => "-*--14-*jisx0208*-0" (specifier-instance (face-font 'default)) # 0xe0028b 0x176b> In this case, `specifier-instance' returns an opaque object; programs can't work on it, they can only pass it around. Worse, in some environments the instantiation will fail, resulting in a different value (when another instantiation succeeds), or worse yet, an error, if all attempts to instance the specifier fail. `specifier-instance' is context-dependent, even for the exact same specification. `specifier-specs' is deterministic, and only depends on the specifications. Note that in the toolbar-changing code we operate in the global locale. This means that narrower locales, if they have specifications, will shadow our changes. (Specifier instancing does not merge specifications. It selects the "highest-priority successful specification" and instances that.) In fact, in our example, it seems pretty likely that different buffers _should_ have different buttons. (The icon can be the same, but the keyboard macro you create in a Dired buffer is highly unlikely to be useful in a LaTeX buffer!) Here's one way to implement this: (setq toolbar-my-kbd-macro-button `[ (list (make-glyph "MyKbdMac")) (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) t "Execute a previously defined keyboard macro." ]) (set-specifier default-toolbar (cons toolbar-my-kbd-macro-button (cond ((specifier-specs default-toolbar (current-buffer))) ((specifier-specs default-toolbar 'global))) (current-buffer)) Finally, a cautionary note: the use of `specifier-specs' in the code above is for expository purposes. Don't use it in production code. In fact, the `set-specifier' form above is likely to fail occasionally, because you can add many specifications for the same locale. In these cases, `specifier-specs' will return a list. A further refinement is that a specification may be associated with a set of "specifier tags". If the list of specifier tags is non-nil, then `specifier-specs' will return a cons of the tag set and the instantiator. Evidently `specifier-specs' is a bit unreliable. (For toolbars, the code above should work 99% of the time, because toolbars are rarely changed. Since instantiation is trivial, multiple specs are not useful--the first one always succeeds.) In fact, `specifier-specs' is intended to be used to display specs to humans with a minimum of clutter. The robust way to access specifications is via `specifier-spec-list'. *Note Adding Specifications::, for the definition of "spec-list". *Note Retrieving Specifications::, for documentation of `specifier-specs' and `specifier-spec-list'. To get the desired effect, replace the form `(specifier-spec default-toolbar 'global)' with (cdr (second (first (specifier-spec-list default-toolbar 'global)))) (It should be obvious why the example uses the lazy unreliable method!)  File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Simple Specifier Usage, Up: Specifiers In-Depth Overview of a Specifier ================================ Having variables vary according the editing context is very useful, and the buffer is the natural "atomic" unit of editing context. In a GUI environment, it can be similarly useful to have variables whose values vary according to display context. The atomic unit of display context is the Emacs window. Buffers are cleanly grouped by modes, but windows are not so easily pigeonholed. On the one hand, a window displays a buffer, and thus one possible hierarchy is window, buffer, mode. On the other, a window is a component of a frame. This generates the window, frame, device hierarchy. Finally, there are objects such as toolbars whose properties are described by specifiers. These do not fit naturally into either hierarchy. This problem is as yet not cleanly solved. Another potential source of conceptual confusion is the instantiation process. Instantiating a buffer-local variable is simple: at any given point in time there is a current buffer, and its local values are used and set whenever the variable is accessed, unless the programmer goes to some special effort (uses `default-value' and `set-default'. However, a specifier object encapsulates a set of "specifications", each of which says what its value should be if a particular condition applies. Several such conditions might apply simultaneously in a given window. For example, one specification might be "The value should be darkseagreen2 on X devices" another might be "The value should be blue in the *Help* buffer". So what do we do for "the *Help* buffer on an X device"? The answer is simple: give each type of locale a priority and check them in priority order, returning the first instantiator that successfully instantiates a value. Given a specifier, a logical question is "What is its value in a particular situation?" This involves looking through the specifications to see which ones apply to this particular situation, and perhaps preferring one over another if more than one applies. In specifier terminology, a "particular situation" is called a "domain", and determining its value in a particular domain is called "instancing". Most of the time, a domain is identified by a particular window. For example, if the redisplay engine is drawing text in the default face in a particular window, it retrieves the specifier for the foreground color of the default face and "instances" it in the domain given by that window; in other words, it asks the specifier, "What is your value in this window?". Note that the redisplay example is in a sense canonical. That is, specifiers are designed to present a uniform and _efficient_ API to redisplay. It is the efficiency constraint that motivates the introduction of specifier tags, and many restrictions on access (for example, a buffer is not a domain, and you cannot instantiate a specifier over a buffer). More specifically, a specifier contains a set of "specifications", each of which associates a "locale" (a window object, a buffer object, a frame object, a device object, or the symbol `global') with an "inst-list", which is a list of one or more "inst-pairs". (For each possible locale, there can be at most one specification containing that locale.) Each inst-pair is a cons of a "tag set" (an unordered list of zero or more symbols, or "tags") and an "instantiator" (the allowed form of this varies depending on the type of specifier). In a given specification, there may be more than one inst-pair with the same tag set; this is unlike for locales. The tag set is used to restrict the sorts of devices over which the instantiator is valid and to uniquely identify instantiators added by a particular application, so that different applications can work on the same specifier and not interfere with each other. Each tag can have a "predicate" associated with it, which is a function of one argument (a device) that specifies whether the tag matches that particular device. (If a tag does not have a predicate, it matches all devices.) All tags in a tag set must match a device for the associated inst-pair to be instantiable over that device. (A null tag set is perfectly valid, and trivially matches all devices.) The valid device types (normally `x', `tty', and `stream') and device classes (normally `color', `grayscale', and `mono') can always be used as tags, and match devices of the associated type or class (*note Consoles and Devices::). User-defined tags may be defined, with an optional predicate specified. An application can create its own tag, use it to mark all its instantiators, and be fairly confident that it will not interfere with other applications that modify the same specifier--Functions that add a specification to a specifier usually only overwrite existing inst-pairs with the same tag set as was given, and a particular tag or tag set can be specified when removing instantiators. When a specifier is instanced in a domain, both the locale and the tag set can be viewed as specifying necessary conditions that must apply in that domain for an instantiator to be considered as a possible result of the instancing. More specific locales always override more general locales (thus, there is no particular ordering of the specifications in a specifier); however, the tag sets are simply considered in the order that the inst-pairs occur in the specification's inst-list. Note also that the actual object that results from the instancing (called an "instance object") may not be the same as the instantiator from which it was derived. For some specifier types (such as integer specifiers and boolean specifiers), the instantiator will be returned directly as the instance object. For other types, however, this is not the case. For example, for font specifiers, the instantiator is a font-description string and the instance object is a font-instance object, which describes how the font is displayed on a particular device. A font-instance object encapsulates such things as the actual font name used to display the font on that device (a font-description string under X is usually a wildcard specification that may resolve to different font names, with possibly different foundries, widths, etc., on different devices), the extra properties of that font on that device, etc. Furthermore, this conversion (called "instantiation") might fail--a font or color might not exist on a particular device, for example.  File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers How a Specifier Is Instanced ============================ Instancing of a specifier in a particular window domain proceeds as follows: * First, XEmacs searches for a specification whose locale is the same as the window. If that fails, the search is repeated, looking for a locale that is the same as the window's buffer. If that fails, the search is repeated using the window's frame, then using the device that frame is on. Finally, the specification whose locale is the symbol `global' (if there is such a specification) is considered. * The inst-pairs contained in the specification that was found are considered in their order in the inst-list, looking for one whose tag set matches the device that is derived from the window domain. (The tag set is an unordered list of zero or more tag symbols. For all tags that have predicates associated with them, the predicate must match the device.) * If a matching tag set is found, the corresponding instantiator is passed to the specifier's instantiation method, which is specific to the type of the specifier. If it succeeds, the resulting instance object is returned as the result of the instancing and the instancing is done. Otherwise, the operation continues, looking for another matching inst-pair in the current specification. * When there are no more inst-pairs to be considered in the current specification, the search starts over, looking for another specification as in the first step above. * If all specifications are exhausted and no instance object can be derived, the instancing fails. (Actually, this is not completely true. Some specifier objects for built-in properties have a "fallback" value, which is either an inst-list or another specifier object, that is consulted if the instancing is about to fail. If it is an inst-list, the searching proceeds using the inst-pairs in that list. If it is a specifier, the entire instancing starts over using that specifier instead of the given one. Fallback values are set by the C code and cannot be modified, except perhaps indirectly, using any Lisp functions. The purpose of them is to supply some values to make sure that instancing of built-in properties can't fail and to implement some basic specifier inheritance, such as the fact that faces inherit their properties from the `default' face.) It is also possible to instance a specifier over a frame domain or device domain instead of over a window domain. The C code, for example, instances the `top-toolbar-height' variable over a frame domain in order to determine the height of a frame's top toolbar. Instancing over a frame or device is similar to instancing over a window except that specifications for locales that cannot be derived from the domain are ignored. Specifically, instancing over a frame looks first for frame locales, then device locales, then the `global' locale. Instancing over a device domain looks only for device locales and the `global' locale.  File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers Specifier Types =============== There are various different types of specifiers. The type of a specifier controls what sorts of instantiators are valid, how an instantiator is instantiated, etc. Here is a list of built-in specifier types: `boolean' The valid instantiators are the symbols `t' and `nil'. Instance objects are the same as instantiators so no special instantiation function is needed. `integer' The valid instantiators are integers. Instance objects are the same as instantiators so no special instantiation function is needed. `modeline-shadow-thickness' is an example of an integer specifier (negative thicknesses indicate that the shadow is drawn recessed instead of raised). `natnum' The valid instantiators are natnums (non-negative integers). Instance objects are the same as instantiators so no special instantiation function is needed. Natnum specifiers are used for dimension variables such as `top-toolbar-height'. `generic' All Lisp objects are valid instantiators. Instance objects are the same as instantiators so no special instantiation function is needed. `font' The valid instantiators are strings describing fonts or vectors indicating inheritance from the font of some face. Instance objects are font-instance objects, which are specific to a particular device. The instantiation method for font specifiers can fail, unlike for integer, natnum, boolean, and generic specifiers. `color' The valid instantiators are strings describing colors or vectors indicating inheritance from the foreground or background of some face. Instance objects are color-instance objects, which are specific to a particular device. The instantiation method for color specifiers can fail, as for font specifiers. `image' Images are perhaps the most complicated type of built-in specifier. The valid instantiators are strings (a filename, inline data for a pixmap, or text to be displayed in a text glyph) or vectors describing inline data of various sorts or indicating inheritance from the background-pixmap property of some face. Instance objects are either strings (for text images), image-instance objects (for pixmap images), or subwindow objects (for subwindow images). The instantiation method for image specifiers can fail, as for font and color specifiers. `face-boolean' The valid instantiators are the symbols `t' and `nil' and vectors indicating inheritance from a boolean property of some face. Specifiers of this sort are used for all of the built-in boolean properties of faces. Instance objects are either the symbol `t' or the symbol `nil'. `toolbar' The valid instantiators are toolbar descriptors, which are lists of toolbar-button descriptors (each of which is a vector of two or four elements). *Note Toolbar::, for more information. Color and font instance objects can also be used in turn as instantiators for a new color or font instance object. Since these instance objects are device-specific, the instantiator can be used directly as the new instance object, but only if they are of the same device. If the devices differ, the base color or font of the instantiating object is effectively used instead as the instantiator. *Note Faces and Window-System Objects::, for more information on fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more information about image specifiers. *Note Toolbar::, for more information on toolbar specifiers. - Function: specifier-type specifier This function returns the type of SPECIFIER. The returned value will be a symbol: one of `integer', `boolean', etc., as listed in the above table. Functions are also provided to query whether an object is a particular kind of specifier: - Function: boolean-specifier-p object This function returns non-`nil' if OBJECT is a boolean specifier. - Function: integer-specifier-p object This function returns non-`nil' if OBJECT is an integer specifier. - Function: natnum-specifier-p object This function returns non-`nil' if OBJECT is a natnum specifier. - Function: generic-specifier-p object This function returns non-`nil' if OBJECT is a generic specifier. - Function: face-boolean-specifier-p object This function returns non-`nil' if OBJECT is a face-boolean specifier. - Function: toolbar-specifier-p object This function returns non-`nil' if OBJECT is a toolbar specifier. - Function: font-specifier-p object This function returns non-`nil' if OBJECT is a font specifier. - Function: color-specifier-p object This function returns non-`nil' if OBJECT is a color specifier. - Function: image-specifier-p object This function returns non-`nil' if OBJECT is an image specifier.  File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers Adding specifications to a Specifier ==================================== - Function: add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add This function adds a specification to SPECIFIER. The specification maps from LOCALE (which should be a window, buffer, frame, device, or the symbol `global', and defaults to `global') to INSTANTIATOR, whose allowed values depend on the type of the specifier. Optional argument TAG-SET limits the instantiator to apply only to the specified tag set, which should be a list of tags all of which must match the device being instantiated over (tags are a device type, a device class, or tags defined with `define-specifier-tag'). Specifying a single symbol for TAG-SET is equivalent to specifying a one-element list containing that symbol. Optional argument HOW-TO-ADD specifies what to do if there are already specifications in the specifier. It should be one of `prepend' Put at the beginning of the current list of instantiators for LOCALE. `append' Add to the end of the current list of instantiators for LOCALE. `remove-tag-set-prepend' This is the default. Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the beginning of the current list. `remove-tag-set-append' Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the end of the current list. `remove-locale' Remove all previous instantiators for this locale before adding the new spec. `remove-locale-type' Remove all specifications for all locales of the same type as LOCALE (this includes LOCALE itself) before adding the new spec. `remove-all' Remove all specifications from the specifier before adding the new spec. `remove-tag-set-prepend' is the default. You can retrieve the specifications for a particular locale or locale type with the function `specifier-spec-list' or `specifier-specs'. - Function: add-spec-list-to-specifier specifier spec-list &optional how-to-add This function adds a "spec-list" (a list of specifications) to SPECIFIER. The format of a spec-list is `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' where * LOCALE := a window, a buffer, a frame, a device, or `global' * TAG-SET := an unordered list of zero or more TAGS, each of which is a symbol * TAG := a device class (*note Consoles and Devices::), a device type, or a tag defined with `define-specifier-tag' * INSTANTIATOR := format determined by the type of specifier The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A list of inst-pairs is called an "inst-list". The pair `(LOCALE . INST-LIST)' is called a "specification". A spec-list, then, can be viewed as a list of specifications. HOW-TO-ADD specifies how to combine the new specifications with the existing ones, and has the same semantics as for `add-spec-to-specifier'. The higher-level function `set-specifier' is often more convenient because it allows abbreviations of spec-lists to be used instead of the heavily nested canonical syntax. However, one should take great care in using them with specifiers types which can have lists as instantiators, such as toolbar specifiers and generic specifiers. In those cases it's probably best to use `add-spec-to-specifier' or `add-spec-list-to-specifier'. - Special Form: let-specifier specifier-list &rest body This special form temporarily adds specifications to specifiers, evaluates forms in BODY and restores the specifiers to their previous states. The specifiers and their temporary specifications are listed in SPECIFIER-LIST. The format of SPECIFIER-LIST is ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) SPECIFIER is the specifier to be temporarily modified. VALUE is the instantiator to be temporarily added to specifier in LOCALE. LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in `add-spec-to-specifier'. This special form is implemented as a macro; the code resulting from macro expansion will add specifications to specifiers using `add-spec-to-specifier'. After forms in BODY are evaluated, the temporary specifications are removed and old specifier spec-lists are restored. LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to `nil'. The value of the last form in BODY is returned. NOTE: If you want the specifier's instance to change in all circumstances, use `(selected-window)' as the LOCALE. If LOCALE is `nil' or omitted, it defaults to `global'. The following example removes the 3D modeline effect in the currently selected window for the duration of a second: (let-specifier ((modeline-shadow-thickness 0 (selected-window))) (sit-for 1)) - Function: set-specifier specifier value &optional locale tag-set how-to-add This function adds some specifications to SPECIFIER. VALUE can be a single instantiator or tagged instantiator (added as a global specification), a list of tagged and/or untagged instantiators (added as a global specification), a cons of a locale and instantiator or locale and instantiator list, a list of such conses, or nearly any other reasonable form. More specifically, VALUE can be anything accepted by `canonicalize-spec-list' (described below). LOCALE, TAG-SET, and HOW-TO-ADD are the same as in `add-spec-to-specifier'. Note that `set-specifier' is exactly complementary to `specifier-specs' except in the case where SPECIFIER has no specs at all in it but `nil' is a valid instantiator (in that case, `specifier-specs' will return `nil' (meaning no specs) and `set-specifier' will interpret the `nil' as meaning "I'm adding a global instantiator and its value is `nil'"), or in strange cases where there is an ambiguity between a spec-list and an inst-list, etc. (The built-in specifier types are designed in such a way as to avoid any such ambiguities.) For robust code, `set-specifier' should probably be avoided for specifier types which accept lists as instantiators (currently toolbar specifiers and generic specifiers). If you want to work with spec-lists, you should probably not use these functions, but should use the lower-level functions `specifier-spec-list' and `add-spec-list-to-specifier'. These functions always work with fully-qualified spec-lists; thus, there is no ambiguity. - Function: canonicalize-inst-pair inst-pair specifier-type &optional noerror This function canonicalizes the given INST-PAIR. SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for an inst-pair, i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator is given a tag set of `nil' (the empty set), and a single tag is converted into a tag set consisting only of that tag. If NOERROR is non-`nil', signal an error if the inst-pair is invalid; otherwise return `t'. - Function: canonicalize-inst-list inst-list specifier-type &optional noerror This function canonicalizes the given INST-LIST (a list of inst-pairs). SPECIFIER-TYPE specifies the type of specifier that this INST-LIST will be used for. Canonicalizing means converting to the full form for an inst-list, i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a single inst-pair or any abbreviation thereof or a list of (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) If NOERROR is non-`nil', signal an error if the inst-list is invalid; otherwise return `t'. - Function: canonicalize-spec spec specifier-type &optional noerror This function canonicalizes the given SPEC (a specification). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for a spec, i.e. `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a possibly abbreviated inst-list or a cons of a locale and a possibly abbreviated inst-list. (See `canonicalize-inst-list'.) If NOERROR is `nil', signal an error if the specification is invalid; otherwise return `t'. - Function: canonicalize-spec-list spec-list specifier-type &optional noerror This function canonicalizes the given SPEC-LIST (a list of specifications). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. If NOERROR is `nil', signal an error if the spec-list is invalid; otherwise return `t' for an invalid spec-list. (Note that this cannot be confused with a canonical spec-list.) Canonicalizing means converting to the full form for a spec-list, i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This function accepts a possibly abbreviated specification or a list of such things. (See `canonicalize-spec'.) This is the function used to convert spec-lists accepted by `set-specifier' and such into a form suitable for `add-spec-list-to-specifier'. This function tries extremely hard to resolve any ambiguities, and the built-in specifier types (font, image, toolbar, etc.) are designed so that there won't be any ambiguities. The canonicalization algorithm is as follows: 1. Attempt to parse SPEC-LIST as a single, possibly abbreviated, specification. 2. If that fails, attempt to parse SPEC-LIST as a list of (abbreviated) specifications. 3. If that fails, SPEC-LIST is invalid. A possibly abbreviated specification SPEC is parsed by 1. Attempt to parse SPEC as a possibly abbreviated inst-list. 2. If that fails, attempt to parse SPEC as a cons of a locale and an (abbreviated) inst-list. 3. If that fails, SPEC is invalid. A possibly abbreviated inst-list INST-LIST is parsed by 1. Attempt to parse INST-LIST as a possibly abbreviated inst-pair. 2. If that fails, attempt to parse INST-LIST as a list of (abbreviated) inst-pairs. 3. If that fails, INST-LIST is invalid. A possibly abbreviated inst-pair INST-PAIR is parsed by 1. Check if INST-PAIR is `valid-instantiator-p'. 2. If not, check if INST-PAIR is a cons of something that is a tag, ie, `valid-specifier-tag-p', and something that is `valid-instantiator-p'. 3. If not, check if INST-PAIR is a cons of a list of tags and something that is `valid-instantiator-p'. 4. Otherwise, INST-PAIR is invalid. In summary, this function generally prefers more abbreviated forms.  File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers Retrieving the Specifications from a Specifier ============================================== - Function: specifier-spec-list specifier &optional locale tag-set exact-p This function returns the spec-list of specifications for SPECIFIER in LOCALE. If LOCALE is a particular locale (a window, buffer, frame, device, or the symbol `global'), a spec-list consisting of the specification for that locale will be returned. If LOCALE is a locale type (i.e. one of the symbols `window', `buffer', `frame', or `device'), a spec-list of the specifications for all locales of that type will be returned. If LOCALE is `nil' or the symbol `all', a spec-list of all specifications in SPECIFIER will be returned. LOCALE can also be a list of locales, locale types, and/or `all'; the result is as if `specifier-spec-list' were called on each element of the list and the results concatenated together. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are returned. (The default value of `nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be returned. - Function: specifier-specs specifier &optional locale tag-set exact-p This function returns the specification(s) for SPECIFIER in LOCALE. If LOCALE is a single locale or is a list of one element containing a single locale, then a "short form" of the instantiators for that locale will be returned. Otherwise, this function is identical to `specifier-spec-list'. The "short form" is designed for readability and not for ease of use in Lisp programs, and is as follows: 1. If there is only one instantiator, then an inst-pair (i.e. cons of tag and instantiator) will be returned; otherwise a list of inst-pairs will be returned. 2. For each inst-pair returned, if the instantiator's tag is `any', the tag will be removed and the instantiator itself will be returned instead of the inst-pair. 3. If there is only one instantiator, its value is `nil', and its tag is `any', a one-element list containing `nil' will be returned rather than just `nil', to distinguish this case from there being no instantiators at all. - Function: specifier-fallback specifier This function returns the fallback value for SPECIFIER. Fallback values are provided by the C code for certain built-in specifiers to make sure that instancing won't fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that faces other than `default' inherit their attributes from `default'). By design, you cannot change the fallback value, and specifiers created with `make-specifier' will never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance). The fallback value will be an inst-list that is instanced like any other inst-list, a specifier of the same type as SPECIFIER (results in inheritance), or `nil' for no fallback. When you instance a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See `specifier-instance'.  File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers Working With Specifier Tags =========================== A specifier tag set is an entity that is attached to an instantiator and can be used to restrict the scope of that instantiator to a particular device class or device type and/or to mark instantiators added by a particular package so that they can be later removed. A specifier tag set consists of a list of zero or more specifier tags, each of which is a symbol that is recognized by XEmacs as a tag. (The valid device types and device classes are always tags, as are any tags defined by `define-specifier-tag'.) It is called a "tag set" (as opposed to a list) because the order of the tags or the number of times a particular tag occurs does not matter. Each tag has a predicate associated with it, which specifies whether that tag applies to a particular device. The tags which are device types and classes match devices of that type or class. User-defined tags can have any predicate, or none (meaning that all devices match). When attempting to instance a specifier, a particular instantiator is only considered if the device of the domain being instanced over matches all tags in the tag set attached to that instantiator. Most of the time, a tag set is not specified, and the instantiator gets a null tag set, which matches all devices. - Function: valid-specifier-tag-p tag This function returns non-`nil' if TAG is a valid specifier tag. - Function: valid-specifier-tag-set-p tag-set This function returns non-`nil' if TAG-SET is a valid specifier tag set. - Function: canonicalize-tag-set tag-set This function canonicalizes the given tag set. Two canonicalized tag sets can be compared with `equal' to see if they represent the same tag set. (Specifically, canonicalizing involves sorting by symbol name and removing duplicates.) - Function: device-matches-specifier-tag-set-p device tag-set This function returns non-`nil' if DEVICE matches specifier tag set TAG-SET. This means that DEVICE matches each tag in the tag set. - Function: define-specifier-tag tag &optional predicate This function defines a new specifier tag. If PREDICATE is specified, it should be a function of one argument (a device) that specifies whether the tag matches that particular device. If PREDICATE is omitted, the tag matches all devices. You can redefine an existing user-defined specifier tag. However, you cannot redefine the built-in specifier tags (the device types and classes) or the symbols `nil', `t', `all', or `global'. - Function: device-matching-specifier-tag-list &optional device This function returns a list of all specifier tags matching DEVICE. DEVICE defaults to the selected device if omitted. - Function: specifier-tag-list This function returns a list of all currently-defined specifier tags. This includes the built-in ones (the device types and classes). - Function: specifier-tag-predicate tag This function returns the predicate for the given specifier tag.  File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Examples, Prev: Specifier Tag Functions, Up: Specifiers Functions for Instancing a Specifier ==================================== - Function: specifier-instance specifier &optional domain default no-fallback This function instantiates SPECIFIER (returns its value) in DOMAIN. If no instance can be generated for this domain, return DEFAULT. DOMAIN should be a window, frame, or device. Other values that are legal as a locale (e.g. a buffer) are not valid as a domain because they do not provide enough information to identify a particular device (see `valid-specifier-domain-p'). DOMAIN defaults to the selected window if omitted. "Instantiating" a specifier in a particular domain means determining the specifier's "value" in that domain. This is accomplished by searching through the specifications in the specifier that correspond to all locales that can be derived from the given domain, from specific to general. In most cases, the domain is an Emacs window. In that case specifications are searched for as follows: 1. A specification whose locale is the window itself; 2. A specification whose locale is the window's buffer; 3. A specification whose locale is the window's frame; 4. A specification whose locale is the window's frame's device; 5. A specification whose locale is the symbol `global'. If all of those fail, then the C-code-provided fallback value for this specifier is consulted (see `specifier-fallback'). If it is an inst-list, then this function attempts to instantiate that list just as when a specification is located in the first five steps above. If the fallback is a specifier, `specifier-instance' is called recursively on this specifier and the return value used. Note, however, that if the optional argument NO-FALLBACK is non-`nil', the fallback value will not be consulted. Note that there may be more than one specification matching a particular locale; all such specifications are considered before looking for any specifications for more general locales. Any particular specification that is found may be rejected because it is tagged to a particular device class (e.g. `color') or device type (e.g. `x') or both and the device for the given domain does not match this, or because the specification is not valid for the device of the given domain (e.g. the font or color name does not exist for this particular X server). The returned value is dependent on the type of specifier. For example, for a font specifier (as returned by the `face-font' function), the returned value will be a font-instance object. For images, the returned value will be a string, pixmap, or subwindow. - Function: specifier-matching-instance specifier matchspec &optional domain default no-fallback This function returns an instance for SPECIFIER in DOMAIN that matches MATCHSPEC. If no instance can be generated for DOMAIN, return DEFAULT. This function is identical to `specifier-instance' except that a specification will only be considered if it matches MATCHSPEC. The definition of "match," and allowed values for MATCHSPEC, are dependent on the particular type of specifier. Here are some examples: * For chartable (e.g. display table) specifiers, MATCHSPEC should be a character, and the specification (a chartable) must give a value for that character in order to be considered. This allows you to specify, _e.g._, a buffer-local display table that only gives values for particular characters. All other characters are handled as if the buffer-local display table is not there. (Chartable specifiers are not yet implemented.) * For font specifiers, MATCHSPEC should be a charset, and the specification (a font string) must have a registry that matches the charset's registry. (This only makes sense with Mule support.) This makes it easy to choose a font that can display a particular character. (This is what redisplay does, in fact.) - Function: specifier-instance-from-inst-list specifier domain inst-list &optional default This function attempts to convert a particular inst-list into an instance. This attempts to instantiate INST-LIST in the given DOMAIN, as if INST-LIST existed in a specification in SPECIFIER. If the instantiation fails, DEFAULT is returned. In most circumstances, you should not use this function; use `specifier-instance' instead.  File: lispref.info, Node: Specifier Examples, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers Examples of Specifier Usage =========================== Now let us present an example to clarify the theoretical discussions we have been through. In this example, we will use the general specifier functions for clarity. Keep in mind that many types of specifiers, and some other types of objects that are associated with specifiers (e.g. faces), provide convenience functions making it easier to work with objects of that type. Let us consider the background color of the default face. A specifier is used to specify how that color will appear in different domains. First, let's retrieve the specifier: (setq sp (face-property 'default 'background)) => # (specifier-specs sp) => ((# (nil . "forest green")) (# (nil . "hot pink")) (# (nil . "puke orange") (nil . "moccasin")) (# (nil . "magenta")) (global ((tty) . "cyan") (nil . "white")) ) Then, say we want to determine what the background color of the default face is for the window currently displaying the buffer `*scratch*'. We call (get-buffer-window "*scratch*") => # (window-frame (get-buffer-window "*scratch*")) => # (specifier-instance sp (get-buffer-window "*scratch*")) => # Note that we passed a window to `specifier-instance', not a buffer. We cannot pass a buffer because a buffer by itself does not provide enough information. The buffer might not be displayed anywhere at all, or could be displayed in many different frames on different devices. The result is arrived at like this: 1. First, we look for a specification matching the buffer displayed in the window, i.e. `*scratch*'. There are none, so we proceed. 2. Then, we look for a specification matching the window itself. Again, there are none. 3. Then, we look for a specification matching the window's frame. The specification `(# . "puke orange")' is found. We call the instantiation method for colors, passing it the locale we were searching over (i.e. the window, in this case) and the instantiator (`"puke orange"'). However, the particular device which this window is on (let's say it's an X connection) doesn't recognize the color `"puke orange"', so the specification is rejected. 4. So we continue looking for a specification matching the window's frame. We find `(# . "moccasin")'. Again, we call the instantiation method for colors. This time, the X server our window is on recognizes the color `moccasin', and so the instantiation method succeeds and returns a color instance. Here's another example, which implements something like GNU Emacs's "frame-local" variables. ;; Implementation ;; There are probably better ways to write this macro ;; Heaven help you if VAR is a buffer-local; you will become very ;; confused. Probably should error on that. (defmacro define-frame-local-variable (var) "Make the unbound symbol VAR become a frame-local variable." (let ((val (if (boundp var) (symbol-value var) nil))) `(progn (setq ,var (make-specifier 'generic)) (add-spec-to-specifier ,var ',val 'global)))) ;; I'm not real happy about this terminology, how can `setq' be a defun? ;; But `frame-set' would have people writing "(frame-set 'foo value)". (defun frame-setq (var value &optional frame) "Set the local value of VAR to VALUE in FRAME. FRAME defaults to the selected frame." (and frame (not (framep frame)) (error 'invalid-argument "FRAME must be a frame", frame)) (add-spec-to-specifier var value (or frame (selected-frame)))) (defun frame-value (var &optional frame) "Get the local value of VAR in FRAME. FRAME defaults to the selected frame." (and frame (not (framep frame)) (error 'invalid-argument "FRAME must be a frame", frame)) ;; this is not just a map from frames to values; it also falls back ;; to the global value (specifier-instance var (or frame (selected-frame)))) ;; for completeness (defun frame-set-default (var value) "Set the default value of frame-local variable VAR to VALUE." (add-spec-to-specifier var value 'global)) (defun frame-get-default (var) "Get the default value of frame-local variable VAR." (car (specifier-specs var 'global))) Now you can execute the above definitions (eg, with `eval-last-sexp') and switch to `*scratch*' to play. Things will work differently if you already have a variable named `foo'. ;; Usage foo error--> Symbol's value as variable is void: foo (define-frame-local-variable foo) => nil ;; the value of foo is a specifier, which is an opaque object; ;; you must use accessor functions to get values foo => # ;; since no frame-local value is set, the global value (which is the ;; constant `nil') is returned (frame-value foo) => nil ;; get the default explicitly (frame-get-default foo) => nil ;; get the whole specification list (specifier-specs foo 'global) => (nil) ;; give foo a frame-local value (frame-setq foo 'bar) => nil ;; access foo in several ways ;; Note that the print function for this kind of specifier only ;; gives you the global setting. To get the full list of specs for ;; debugging or study purposes, you must use specifier-specs or ;; specifier-spec-list. foo => # ;; get the whole specification list (specifier-specs foo) => ((# (nil . bar)) (global (nil))) ;; get the frame-local value (frame-value foo) => bar ;; get the default explicitly (frame-get-default foo) => nil ;; Switch to another frame and evaluate: ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET => baz ;; Switch back. ;; C-x 5 o (specifier-specs foo) => ((# (nil . baz)) (# (nil . bar)) (global (nil))) (frame-value foo) => bar (frame-get-default foo) => nil Note that since specifiers generalize both frame-local and buffer-local variables in a sensible way, XEmacs is not likely to put a high priority on implementing frame-local variables. In fact, some developers think that frame-local variables are evil for the same reason that buffer-local variables are evil: the declaration is both global and invisible. That is, you cannot tell whether a variable is "normal," buffer-local, or frame-local just by looking at it. So if you have namespace management problems, and some other Lisp package happens to use a variable name that you already declared frame- or buffer-local, weird stuff happens, and it is extremely hard to track down.  File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Examples, Up: Specifiers Creating New Specifier Objects ============================== - Function: make-specifier type This function creates a new specifier. A specifier is an object that can be used to keep track of a property whose value can be per-buffer, per-window, per-frame, or per-device, and can further be restricted to a particular device-type or device-class. Specifiers are used, for example, for the various built-in properties of a face; this allows a face to have different values in different frames, buffers, etc. For more information, see `specifier-instance', `specifier-specs', and `add-spec-to-specifier'; or, for a detailed description of specifiers, including how they are instantiated over a particular domain (i.e. how their value in that domain is determined), see the chapter on specifiers in the XEmacs Lisp Reference Manual. TYPE specifies the particular type of specifier, and should be one of the symbols `generic', `integer', `natnum', `boolean', `color', `font', `image', `face-boolean', or `toolbar'. For more information on particular types of specifiers, see the functions `make-generic-specifier', `make-integer-specifier', `make-natnum-specifier', `make-boolean-specifier', `make-color-specifier', `make-font-specifier', `make-image-specifier', `make-face-boolean-specifier', and `make-toolbar-specifier'. - Function: make-specifier-and-init type spec-list &optional dont-canonicalize This function creates and initializes a new specifier. This is a convenience API combining `make-specifier' and `set-specifier' that allows you to create a specifier and add specs to it at the same time. TYPE specifies the specifier type. Allowed types are as for `make-specifier'. SPEC-LIST supplies the specification(s) to be added to the specifier. Any abbreviation of the full spec-list form accepted by `canonicalize-spec-list' may be used. However, if the optional argument DONT-CANONICALIZE is non-`nil', canonicalization is not performed, and the SPEC-LIST must already be in full form. - Function: make-integer-specifier spec-list Return a new `integer' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. Valid instantiators for integer specifiers are integers. - Function: make-boolean-specifier spec-list Return a new `boolean' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. Valid instantiators for boolean specifiers are `t' and `nil'. - Function: make-natnum-specifier spec-list Return a new `natnum' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. Valid instantiators for natnum specifiers are non-negative integers. - Function: make-generic-specifier spec-list Return a new `generic' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. Valid instantiators for generic specifiers are all Lisp values. They are returned back unchanged when a specifier is instantiated. - Function: make-display-table-specifier spec-list Return a new `display-table' specifier object with the given spec list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. Valid instantiators for display-table specifiers are described in detail in the doc string for `current-display-table' (*note Active Display Table::).  File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers Functions for Checking the Validity of Specifier Components =========================================================== - Function: valid-specifier-domain-p domain This function returns non-`nil' if DOMAIN is a valid specifier domain. A domain is used to instance a specifier (i.e. determine the specifier's value in that domain). Valid domains are a window, frame, or device. (`nil' is not valid.) - Function: valid-specifier-locale-p locale This function returns non-`nil' if LOCALE is a valid specifier locale. Valid locales are a device, a frame, a window, a buffer, and `global'. (`nil' is not valid.) - Function: valid-specifier-locale-type-p locale-type Given a specifier LOCALE-TYPE, this function returns non-`nil' if it is valid. Valid locale types are the symbols `global', `device', `frame', `window', and `buffer'. (Note, however, that in functions that accept either a locale or a locale type, `global' is considered an individual locale.) - Function: valid-specifier-type-p specifier-type Given a SPECIFIER-TYPE, this function returns non-`nil' if it is valid. Valid types are `generic', `integer', `boolean', `color', `font', `image', `face-boolean', and `toolbar'. - Function: valid-specifier-tag-p tag This function returns non-`nil' if TAG is a valid specifier tag. - Function: valid-instantiator-p instantiator specifier-type This function returns non-`nil' if INSTANTIATOR is valid for SPECIFIER-TYPE. - Function: valid-inst-list-p inst-list type This function returns non-`nil' if INST-LIST is valid for specifier type TYPE. - Function: valid-spec-list-p spec-list type This function returns non-`nil' if SPEC-LIST is valid for specifier type TYPE. - Function: check-valid-instantiator instantiator specifier-type This function signals an error if INSTANTIATOR is invalid for SPECIFIER-TYPE. - Function: check-valid-inst-list inst-list type This function signals an error if INST-LIST is invalid for specifier type TYPE. - Function: check-valid-spec-list spec-list type This function signals an error if SPEC-LIST is invalid for specifier type TYPE.  File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers Other Functions for Working with Specifications in a Specifier ============================================================== - Function: copy-specifier specifier &optional dest locale tag-set exact-p how-to-add This function copies SPECIFIER to DEST, or creates a new one if DEST is `nil'. If DEST is `nil' or omitted, a new specifier will be created and the specifications copied into it. Otherwise, the specifications will be copied into the existing specifier in DEST. If LOCALE is `nil' or the symbol `all', all specifications will be copied. If LOCALE is a particular locale, the specification for that particular locale will be copied. If LOCALE is a locale type, the specifications for all locales of that type will be copied. LOCALE can also be a list of locales, locale types, and/or `all'; this is equivalent to calling `copy-specifier' for each of the elements of the list. See `specifier-spec-list' for more information about LOCALE. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are copied. (The default value of `nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be copied. Optional argument HOW-TO-ADD specifies what to do with existing specifications in DEST. If `nil', then whichever locales or locale types are copied will first be completely erased in DEST. Otherwise, it is the same as in `add-spec-to-specifier'. - Function: remove-specifier specifier &optional locale tag-set exact-p This function removes specification(s) for SPECIFIER. If LOCALE is a particular locale (a buffer, window, frame, device, or the symbol `global'), the specification for that locale will be removed. If instead, LOCALE is a locale type (i.e. a symbol `buffer', `window', `frame', or `device'), the specifications for all locales of that type will be removed. If LOCALE is `nil' or the symbol `all', all specifications will be removed. LOCALE can also be a list of locales, locale types, and/or `all'; this is equivalent to calling `remove-specifier' for each of the elements in the list. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are removed. (The default value of `nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be removed. - Function: map-specifier specifier func &optional locale maparg This function applies FUNC to the specification(s) for LOCALE in SPECIFIER. If optional LOCALE is a locale, FUNC will be called for that locale. If LOCALE is a locale type, FUNC will be mapped over all locales of that type. If LOCALE is `nil' or the symbol `all', FUNC will be mapped over all locales in SPECIFIER. Optional MS-MAPARG will be passed to MS-FUNC. FUNC is called with four arguments: the SPECIFIER, the locale being mapped over, the inst-list for that locale, and the optional MAPARG. If any invocation of FUNC returns non-`nil', the mapping will stop and the returned value becomes the value returned from `map-specifier'. Otherwise, `map-specifier' returns `nil'. - Function: specifier-locale-type-from-locale locale Given a specifier LOCALE, this function returns its type.  File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top Faces and Window-System Objects ******************************* * Menu: * Faces:: Controlling the way text looks. * Fonts:: Controlling the typeface of text. * Colors:: Controlling the color of text and pixmaps.  File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects Faces ===== A "face" is a named collection of graphical properties: font, foreground color, background color, background pixmap, optional underlining, and (on TTY devices) whether the text is to be highlighted, dimmed, blinking, or displayed in reverse video. Faces control the display of text on the screen. Every face has a name, which is a symbol such as `default' or `modeline'. Each built-in property of a face is controlled using a specifier, which allows it to have separate values in particular buffers, frames, windows, and devices and to further vary according to device type (X or TTY) and device class (color, mono, or grayscale). *Note Specifiers::, for more information. The face named `default' is used for ordinary text. The face named `modeline' is used for displaying the modeline. The face named `highlight' is used for highlighted extents (*note Extents::). The faces named `left-margin' and `right-margin' are used for the left and right margin areas, respectively (*note Annotations::). The face named `zmacs-region' is used for the highlighted region between point and mark. * Menu: * Merging Faces:: How XEmacs decides which face to use for a character. * Basic Face Functions:: How to define and examine faces. * Face Properties:: How to access and modify a face's properties. * Face Convenience Functions:: Convenience functions for accessing particular properties of a face. * Other Face Display Functions:: Other functions pertaining to how a a face appears.  File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces Merging Faces for Display ------------------------- Here are all the ways to specify which face to use for display of text: * With defaults. Each frame has a "default face", which is used for all text that doesn't somehow specify another face. The face named `default' applies to the text area, while the faces `left-margin' and `right-margin' apply to the left and right margin areas. * With text properties. A character may have a `face' property; if so, it's displayed with that face. (Text properties are actually implemented in terms of extents.) *Note Text Properties::. * With extents. An extent may have a `face' property, which applies to all the text covered by the extent; in addition, if the `highlight' property is set, the `highlight' property applies when the mouse moves over the extent or if the extent is explicitly highlighted. *Note Extents::. * With annotations. Annotations that are inserted into a buffer can specify their own face. (Annotations are actually implemented in terms of extents.) *Note Annotations::. If these various sources together specify more than one face for a particular character, XEmacs merges the properties of the various faces specified. Extents, text properties, and annotations all use the same underlying representation (as extents). When multiple extents cover one character, an extent with higher priority overrides those with lower priority. *Note Extents::. If no extent covers a particular character, the `default' face is used. If a background pixmap is specified, it determines what will be displayed in the background of text characters. If the background pixmap is actually a pixmap, with its colors specified, those colors are used; if it is a bitmap, the face's foreground and background colors are used to color it.  File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces Basic Functions for Working with Faces -------------------------------------- The properties a face can specify include the font, the foreground color, the background color, the background pixmap, the underlining, the display table, and (for TTY devices) whether the text is to be highlighted, dimmed, blinking, or displayed in reverse video. The face can also leave these unspecified, causing them to assume the value of the corresponding property of the `default' face. Here are the basic primitives for working with faces. - Function: make-face name &optional doc-string temporary This function defines and returns a new face named NAME, initially with all properties unspecified. It does nothing if there is already a face named NAME. Optional argument DOC-STRING specifies an explanatory string used for descriptive purposes. If optional argument TEMPORARY is non-`nil', the face will automatically disappear when there are no more references to it anywhere in text or Lisp code (otherwise, the face will continue to exist indefinitely even if it is not used). - Function: face-list &optional temporary This function returns a list of the names of all defined faces. If TEMPORARY is `nil', only the permanent faces are included. If it is `t', only the temporary faces are included. If it is any other non-`nil' value both permanent and temporary are included. - Function: facep object This function returns `t' if OBJECT is a face, else `nil'. - Function: copy-face old-face new-name &optional locale tag-set exact-p how-to-add This function defines a new face named NEW-NAME which is a copy of the existing face named OLD-FACE. If there is already a face named NEW-NAME, then it alters the face to have the same properties as OLD-FACE. LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of the old face rather than the whole face, and are as in `copy-specifier' (*note Specifiers::).  File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces Face Properties --------------- You can examine and modify the properties of an existing face with the following functions. The following symbols have predefined meanings: `foreground' The foreground color of the face. `background' The background color of the face. `font' The font used to display text covered by this face. `display-table' The display table of the face. `background-pixmap' The pixmap displayed in the background of the face. Only used by faces on X devices. `underline' Underline all text covered by this face. `highlight' Highlight all text covered by this face. Only used by faces on TTY devices. `dim' Dim all text covered by this face. Only used by faces on TTY devices. `blinking' Blink all text covered by this face. Only used by faces on TTY devices. `reverse' Reverse the foreground and background colors. Only used by faces on TTY devices. `doc-string' Description of what the face's normal use is. NOTE: This is not a specifier, unlike all the other built-in properties, and cannot contain locale-specific values. - Function: set-face-property face property value &optional locale tag-set how-to-add This function changes a property of a FACE. For built-in properties, the actual value of the property is a specifier and you cannot change this; but you can change the specifications within the specifier, and that is what this function will do. For user-defined properties, you can use this function to either change the actual value of the property or, if this value is a specifier, change the specifications within it. If PROPERTY is a built-in property, the specifications to be added to this property can be supplied in many different ways: If VALUE is a simple instantiator (e.g. a string naming a font or color) or a list of instantiators, then the instantiator(s) will be added as a specification of the property for the given LOCALE (which defaults to `global' if omitted). If VALUE is a list of specifications (each of which is a cons of a locale and a list of instantiators), then LOCALE must be `nil' (it does not make sense to explicitly specify a locale in this case), and specifications will be added as given. If VALUE is a specifier (as would be returned by `face-property' if no LOCALE argument is given), then some or all of the specifications in the specifier will be added to the property. In this case, the function is really equivalent to `copy-specifier' and LOCALE has the same semantics (if it is a particular locale, the specification for the locale will be copied; if a locale type, specifications for all locales of that type will be copied; if `nil' or `all', then all specifications will be copied). HOW-TO-ADD should be either `nil' or one of the symbols `prepend', `append', `remove-tag-set-prepend', `remove-tag-set-append', `remove-locale', `remove-locale-type', or `remove-all'. See `copy-specifier' and `add-spec-to-specifier' for a description of what each of these means. Most of the time, you do not need to worry about this argument; the default behavior usually is fine. In general, it is OK to pass an instance object (e.g. as returned by `face-property-instance') as an instantiator in place of an actual instantiator. In such a case, the instantiator used to create that instance object will be used (for example, if you set a font-instance object as the value of the `font' property, then the font name used to create that object will be used instead). If some cases, however, doing this conversion does not make sense, and this will be noted in the documentation for particular types of instance objects. If PROPERTY is not a built-in property, then this function will simply set its value if LOCALE is `nil'. However, if LOCALE is given, then this function will attempt to add VALUE as the instantiator for the given LOCALE, using `add-spec-to-specifier'. If the value of the property is not a specifier, it will automatically be converted into a `generic' specifier. - Function: remove-face-property face property &optional locale tag-set exact-p This function removes a property of a FACE. For built-in properties, this is analogous to `remove-specifier'. For more information, *Note Other Specification Functions::. When PROPERTY is not a built-in property, this function will just remove its value if LOCALE is `nil' or `all'. However, if LOCALE is other than that, this function will attempt to remove VALUE as the instantiator for the given LOCALE with `remove-specifier'. If the value of the property is not a specifier, it will be converted into a `generic' specifier automatically. - Function: face-property face property &optional locale tag-set exact-p This function returns FACE's value of the given PROPERTY. If LOCALE is omitted, the FACE's actual value for PROPERTY will be returned. For built-in properties, this will be a specifier object of a type appropriate to the property (e.g. a font or color specifier). For other properties, this could be anything. If LOCALE is supplied, then instead of returning the actual value, the specification(s) for the given locale or locale type will be returned. This will only work if the actual value of PROPERTY is a specifier (this will always be the case for built-in properties, but not or not may apply to user-defined properties). If the actual value of PROPERTY is not a specifier, this value will simply be returned regardless of LOCALE. The return value will be a list of instantiators (e.g. strings specifying a font or color name), or a list of specifications, each of which is a cons of a locale and a list of instantiators. Specifically, if LOCALE is a particular locale (a buffer, window, frame, device, or `global'), a list of instantiators for that locale will be returned. Otherwise, if LOCALE is a locale type (one of the symbols `buffer', `window', `frame', or `device'), the specifications for all locales of that type will be returned. Finally, if LOCALE is `all', the specifications for all locales of all types will be returned. The specifications in a specifier determine what the value of PROPERTY will be in a particular "domain" or set of circumstances, which is typically a particular Emacs window along with the buffer it contains and the frame and device it lies within. The value is derived from the instantiator associated with the most specific locale (in the order buffer, window, frame, device, and `global') that matches the domain in question. In other words, given a domain (i.e. an Emacs window, usually), the specifier for PROPERTY will first be searched for a specification whose locale is the buffer contained within that window; then for a specification whose locale is the window itself; then for a specification whose locale is the frame that the window is contained within; etc. The first instantiator that is valid for the domain (usually this means that the instantiator is recognized by the device [i.e. the X server or TTY device] that the domain is on). The function `face-property-instance' actually does all this, and is used to determine how to display the face. - Function: face-property-instance face property &optional domain default no-fallback This function returns the instance of FACE's PROPERTY in the specified DOMAIN. Under most circumstances, DOMAIN will be a particular window, and the returned instance describes how the specified property actually is displayed for that window and the particular buffer in it. Note that this may not be the same as how the property appears when the buffer is displayed in a different window or frame, or how the property appears in the same window if you switch to another buffer in that window; and in those cases, the returned instance would be different. The returned instance will typically be a color-instance, font-instance, or pixmap-instance object, and you can query it using the appropriate object-specific functions. For example, you could use `color-instance-rgb-components' to find out the RGB (red, green, and blue) components of how the `background' property of the `highlight' face is displayed in a particular window. The results might be different from the results you would get for another window (perhaps the user specified a different color for the frame that window is on; or perhaps the same color was specified but the window is on a different X server, and that X server has different RGB values for the color from this one). DOMAIN defaults to the selected window if omitted. DOMAIN can be a frame or device, instead of a window. The value returned for a such a domain is used in special circumstances when a more specific domain does not apply; for example, a frame value might be used for coloring a toolbar, which is conceptually attached to a frame rather than a particular window. The value is also useful in determining what the value would be for a particular window within the frame or device, if it is not overridden by a more specific specification. If PROPERTY does not name a built-in property, its value will simply be returned unless it is a specifier object, in which case it will be instanced using `specifier-instance'. Optional arguments DEFAULT and NO-FALLBACK are the same as in `specifier-instance'. *Note Specifiers::.  File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces Face Convenience Functions -------------------------- - Command: set-face-foreground face color &optional locale tag-set how-to-add - Command: set-face-background face color &optional locale tag-set how-to-add These functions set the foreground (respectively, background) color of face FACE to COLOR. The argument COLOR should be a string (the name of a color) or a color object as returned by `make-color' (*note Colors::). - Command: set-face-background-pixmap face pixmap &optional locale tag-set how-to-add This function sets the background pixmap of face FACE to PIXMAP. The argument PIXMAP should be a string (the name of a bitmap or pixmap file; the directories listed in the variable `x-bitmap-file-path' will be searched) or a glyph object as returned by `make-glyph' (*note Glyphs::). The argument may also be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT are the size in pixels, and DATA is a string, containing the raw bits of the bitmap. - Command: set-face-font face font &optional locale tag-set how-to-add This function sets the font of face FACE. The argument FONT should be a string or a font object as returned by `make-font' (*note Fonts::). - Command: set-face-underline-p face underline-p &optional locale tag-set how-to-add This function sets the underline property of face FACE. - Function: face-foreground face &optional locale tag-set exact-p - Function: face-background face &optional locale tag-set exact-p These functions return the foreground (respectively, background) color specifier of face FACE. *Note Colors::. - Function: face-background-pixmap face &optional locale tag-set exact-p This function return the background-pixmap glyph object of face FACE. - Function: face-font face &optional locale tag-set exact-p This function returns the font specifier of face FACE. (Note: This is not the same as the function `face-font' in FSF Emacs.) *Note Fonts::. - Function: face-font-name face &optional domain This function returns the name of the font of face FACE, or `nil' if it is unspecified. This is basically equivalent to `(font-name (face-font FACE) DOMAIN)' except that it does not cause an error if FACE's font is `nil'. (This function is named `face-font' in FSF Emacs.) - Function: face-underline-p face &optional locale This function returns the underline property of face FACE. - Function: face-foreground-instance face &optional domain - Function: face-background-instance face &optional domain These functions return the foreground (respectively, background) color specifier of face FACE. *Note Colors::. - Function: face-background-pixmap-instance face &optional domain This function return the background-pixmap glyph object of face FACE. - Function: face-font-instance face &optional domain This function returns the font specifier of face FACE. *Note Fonts::.  File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces Other Face Display Functions ---------------------------- - Command: invert-face face &optional locale Swap the foreground and background colors of face FACE. If the face doesn't specify both foreground and background, then its foreground and background are set to the default background and foreground. - Function: face-equal face1 face2 &optional domain This returns `t' if the faces FACE1 and FACE2 will display in the same way. DOMAIN is as in `face-property-instance'. - Function: face-differs-from-default-p face &optional domain This returns `t' if the face FACE displays differently from the default face. DOMAIN is as in `face-property-instance'.  File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects Fonts ===== This section describes how to work with font specifier and font instance objects, which encapsulate fonts in the window system. * Menu: * Font Specifiers:: Specifying how a font will appear. * Font Instances:: What a font specifier gets instanced as. * Font Instance Names:: The name of a font instance. * Font Instance Size:: The size of a font instance. * Font Instance Characteristics:: Display characteristics of font instances. * Font Convenience Functions:: Convenience functions that automatically instance and retrieve the properties of a font specifier.  File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts Font Specifiers --------------- - Function: font-specifier-p object This predicate returns `t' if OBJECT is a font specifier, and `nil' otherwise. - Function: make-font-specifier spec-list Return a new `font' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Valid instantiators for font specifiers are: * A string naming a font (e.g. under X this might be "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point upright medium-weight Courier font). * A font instance (use that instance directly if the device matches, or use the string that generated it). * A vector of no elements (only on TTY's; this means to set no font at all, thus using the "natural" font of the terminal's text). * A vector of one element (a face to inherit from).  File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts Font Instances -------------- - Function: font-instance-p object This predicate returns `t' if OBJECT is a font instance, and `nil' otherwise. - Function: make-font-instance name &optional device noerror This function creates a new font-instance object of the specified name. DEVICE specifies the device this object applies to and defaults to the selected device. An error is signalled if the font is unknown or cannot be allocated; however, if NOERROR is non-`nil', `nil' is simply returned in this case. The returned object is a normal, first-class lisp object. The way you "deallocate" the font is the way you deallocate any other lisp object: you drop all pointers to it and allow it to be garbage collected. When these objects are GCed, the underlying X data is deallocated as well.  File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts Font Instance Names ------------------- - Function: list-fonts pattern &optional device This function returns a list of font names matching the given pattern. DEVICE specifies which device to search for names, and defaults to the currently selected device. - Function: font-instance-name font-instance This function returns the name used to allocate FONT-INSTANCE. - Function: font-instance-truename font-instance This function returns the canonical name of the given font instance. Font names are patterns which may match any number of fonts, of which the first found is used. This returns an unambiguous name for that font (but not necessarily its only unambiguous name).