-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
+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.
-Accessing Elements of Lists
-===========================
+\1f
+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.
- - Function: car cons-cell
- This function returns the value pointed to by the first pointer of
- the cons cell CONS-CELL. Expressed another way, this function
- returns the CAR of CONS-CELL.
+\1f
+File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
- As a special case, if CONS-CELL is `nil', then `car' is defined to
- return `nil'; therefore, any list is a valid argument for `car'.
- An error is signaled if the argument is not a cons cell or `nil'.
+Margins for Filling
+===================
- (car '(a b c))
- => a
- (car '())
- => nil
+ - 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, <LFD> indents to this column. This variable
+ automatically becomes buffer-local when set in any fashion.
- - Function: cdr cons-cell
- This function returns the value pointed to by the second pointer of
- the cons cell CONS-CELL. Expressed another way, this function
- returns the CDR of CONS-CELL.
+\1f
+File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
- As a special case, if CONS-CELL is `nil', then `cdr' is defined to
- return `nil'; therefore, any list is a valid argument for `cdr'.
- An error is signaled if the argument is not a cons cell or `nil'.
+Auto Filling
+============
- (cdr '(a b c))
- => (b c)
- (cdr '())
- => nil
+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::.
- - Function: car-safe object
- This function lets you take the CAR of a cons cell while avoiding
- errors for other data types. It returns the CAR of OBJECT if
- OBJECT is a cons cell, `nil' otherwise. This is in contrast to
- `car', which signals an error if OBJECT is not a list.
-
- (car-safe OBJECT)
- ==
- (let ((x OBJECT))
- (if (consp x)
- (car x)
- nil))
-
- - Function: cdr-safe object
- This function lets you take the CDR of a cons cell while avoiding
- errors for other data types. It returns the CDR of OBJECT if
- OBJECT is a cons cell, `nil' otherwise. This is in contrast to
- `cdr', which signals an error if OBJECT is not a list.
-
- (cdr-safe OBJECT)
- ==
- (let ((x OBJECT))
- (if (consp x)
- (cdr x)
- nil))
-
- - Function: nth n list
- This function returns the Nth element of LIST. Elements are
- numbered starting with zero, so the CAR of LIST is element number
- zero. If the length of LIST is N or less, the value is `nil'.
-
- If N is negative, `nth' returns the first element of LIST.
-
- (nth 2 '(1 2 3 4))
- => 3
- (nth 10 '(1 2 3 4))
- => nil
- (nth -3 '(1 2 3 4))
- => 1
-
- (nth n x) == (car (nthcdr n x))
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. *Note Margins::.
- - Function: nthcdr n list
- This function returns the Nth CDR of LIST. In other words, it
- removes the first N links of LIST and returns what follows.
+ - 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.
- If N is zero or negative, `nthcdr' returns all of LIST. If the
- length of LIST is N or less, `nthcdr' returns `nil'.
+ 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.
- (nthcdr 1 '(1 2 3 4))
- => (2 3 4)
- (nthcdr 10 '(1 2 3 4))
- => nil
- (nthcdr -3 '(1 2 3 4))
- => (1 2 3 4)
-
- Many convenience functions are provided to make it easier for you to
-access particular elements in a nested list. All of these can be
-rewritten in terms of the functions just described.
-
- - Function: caar cons-cell
- - Function: cadr cons-cell
- - Function: cdar cons-cell
- - Function: cddr cons-cell
- - Function: caaar cons-cell
- - Function: caadr cons-cell
- - Function: cadar cons-cell
- - Function: caddr cons-cell
- - Function: cdaar cons-cell
- - Function: cdadr cons-cell
- - Function: cddar cons-cell
- - Function: cdddr cons-cell
- - Function: caaaar cons-cell
- - Function: caaadr cons-cell
- - Function: caadar cons-cell
- - Function: caaddr cons-cell
- - Function: cadaar cons-cell
- - Function: cadadr cons-cell
- - Function: caddar cons-cell
- - Function: cadddr cons-cell
- - Function: cdaaar cons-cell
- - Function: cdaadr cons-cell
- - Function: cdadar cons-cell
- - Function: cdaddr cons-cell
- - Function: cddaar cons-cell
- - Function: cddadr cons-cell
- - Function: cdddar cons-cell
- - Function: cddddr cons-cell
- Each of these functions is equivalent to one or more applications
- of `car' and/or `cdr'. For example,
-
- (cadr x)
-
- is equivalent to
-
- (car (cdr x))
-
- and
-
- (cdaddr x)
-
- is equivalent to
-
- (cdr (car (cdr (cdr x))))
-
- That is to say, read the a's and d's from right to left and apply
- a `car' or `cdr' for each a or d found, respectively.
-
- - Function: first list
- This is equivalent to `(nth 0 LIST)', i.e. the first element of
- LIST. (Note that this is also equivalent to `car'.)
-
- - Function: second list
- This is equivalent to `(nth 1 LIST)', i.e. the second element of
- LIST.
-
- - Function: third list
- - Function: fourth list
- - Function: fifth list
- - Function: sixth list
- - Function: seventh list
- - Function: eighth list
- - Function: ninth list
- - Function: tenth list
- These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
- respectively, i.e. the third through tenth elements of LIST.
-
-\1f
-File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
-
-Building Cons Cells and Lists
-=============================
-
- Many functions build lists, as lists reside at the very heart of
-Lisp. `cons' is the fundamental list-building function; however, it is
-interesting to note that `list' is used more times in the source code
-for Emacs than `cons'.
-
- - Function: cons object1 object2
- This function is the fundamental function used to build new list
- structure. It creates a new cons cell, making OBJECT1 the CAR,
- and OBJECT2 the CDR. It then returns the new cons cell. The
- arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
- often OBJECT2 is a list.
-
- (cons 1 '(2))
- => (1 2)
- (cons 1 '())
- => (1)
- (cons 1 2)
- => (1 . 2)
-
- `cons' is often used to add a single element to the front of a
- list. This is called "consing the element onto the list". For
- example:
-
- (setq list (cons newelt list))
-
- Note that there is no conflict between the variable named `list'
- used in this example and the function named `list' described below;
- any symbol can serve both purposes.
-
- - Function: list &rest objects
- This function creates a list with OBJECTS as its elements. The
- resulting list is always `nil'-terminated. If no OBJECTS are
- given, the empty list is returned.
-
- (list 1 2 3 4 5)
- => (1 2 3 4 5)
- (list 1 2 '(3 4 5) 'foo)
- => (1 2 (3 4 5) foo)
- (list)
- => nil
+ 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.
- - Function: make-list length object
- This function creates a list of length LENGTH, in which all the
- elements have the identical value OBJECT. Compare `make-list'
- with `make-string' (*note Creating Strings::).
+\1f
+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 `\<f\w*\>'. The
+ resulting expression looks like this:
+
+ (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
+ (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.
- (make-list 3 'pigs)
- => (pigs pigs pigs)
- (make-list 0 'pigs)
- => nil
+\1f
+File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text
- - Function: append &rest sequences
- This function returns a list containing all the elements of
- SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
- the last one should be a list. All arguments except the last one
- are copied, so none of them are altered.
-
- More generally, the final argument to `append' may be any Lisp
- object. The final argument is not copied or converted; it becomes
- the CDR of the last cons cell in the new list. If the final
- argument is itself a list, then its elements become in effect
- elements of the result list. If the final element is not a list,
- the result is a "dotted list" since its final CDR is not `nil' as
- required in a true list.
-
- See `nconc' in *Note Rearrangement::, for a way to join lists with
- no copying.
-
- Here is an example of using `append':
-
- (setq trees '(pine oak))
- => (pine oak)
- (setq more-trees (append '(maple birch) trees))
- => (maple birch pine oak)
-
- trees
- => (pine oak)
- more-trees
- => (maple birch pine oak)
- (eq trees (cdr (cdr more-trees)))
- => t
+Counting Columns
+================
- You can see how `append' works by looking at a box diagram. The
- variable `trees' is set to the list `(pine oak)' and then the
- variable `more-trees' is set to the list `(maple birch pine oak)'.
- However, the variable `trees' continues to refer to the original
- list:
-
- more-trees trees
- | |
- | ___ ___ ___ ___ -> ___ ___ ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
- | | | |
- | | | |
- --> maple -->birch --> pine --> oak
-
- An empty sequence contributes nothing to the value returned by
- `append'. As a consequence of this, a final `nil' argument forces
- a copy of the previous argument.
-
- trees
- => (pine oak)
- (setq wood (append trees ()))
- => (pine oak)
- wood
- => (pine oak)
- (eq wood trees)
- => nil
+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).
- This once was the usual way to copy a list, before the function
- `copy-sequence' was invented. *Note Sequences Arrays Vectors::.
+ 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::.
- With the help of `apply', we can append all the lists in a list of
- lists:
+ 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.
- (apply 'append '((a b c) nil (x y z) nil))
- => (a b c x y z)
+ - Function: current-column &optional buffer
+ This function returns the horizontal position of point, measured in
+ columns, counting from 0 at the left margin.
- If no SEQUENCES are given, `nil' is returned:
+ 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.)
- (append)
- => nil
+ Ignores the finite width of frame displaying the buffer, which
+ means that this function may return values greater than
+ `(frame-width)'.
- Here are some examples where the final argument is not a list:
+ 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.
- (append '(x y) 'z)
- => (x y . z)
- (append '(x y) [z])
- => (x y . [z])
+ If BUFFER is nil, the current buffer is assumed.
- The second example shows that when the final argument is a
- sequence but not a list, the sequence's elements do not become
- elements of the resulting list. Instead, the sequence becomes the
- final CDR, like any other non-list final argument.
+ For an example of using `current-column', see the description of
+ `count-lines' in *Note Text Lines::.
- The `append' function also allows integers as arguments. It
- converts them to strings of digits, making up the decimal print
- representation of the integer, and then uses the strings instead
- of the original integers. *Don't use this feature; we plan to
- eliminate it. If you already use this feature, change your
- programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::)
- or `number-to-string' (*note String Conversion::).
+ - 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.
- - Function: reverse list
- This function creates a new list whose elements are the elements of
- LIST, but in reverse order. The original argument LIST is _not_
- altered.
+ 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.
- (setq x '(1 2 3 4))
- => (1 2 3 4)
- (reverse x)
- => (4 3 2 1)
- x
- => (1 2 3 4)
+ 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.
-\1f
-File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
+ 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.
-Modifying Existing List Structure
-=================================
+ If COLUMN is not a non-negative integer, an error is signaled.
+
+ The return value is the column number actually moved to.
+
+\1f
+File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text
- You can modify the CAR and CDR contents of a cons cell with the
-primitives `setcar' and `setcdr'.
+Indentation
+===========
- Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
- to alter list structure; they change structure the same way as
- `setcar' and `setcdr', but the Common Lisp functions return the
- cons cell while `setcar' and `setcdr' return the new CAR or CDR.
+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:
-* Setcar:: Replacing an element in a list.
-* Setcdr:: Replacing part of the list backbone.
- This can be used to remove or add elements.
-* Rearrangement:: Reordering the elements in a list; combining lists.
+* 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.
\1f
-File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists
+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.
-Altering List Elements with `setcar'
+\1f
+File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation
+
+Indentation Controlled by Major Mode
------------------------------------
- Changing the CAR of a cons cell is done with `setcar'. When used on
-a list, `setcar' replaces one element of a list with a different
-element.
+An important function of each major mode is to customize the <TAB> key
+to indent properly for the language being edited. This section
+describes the mechanism of the <TAB> 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 <TAB> (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 <TAB> does,
+ but in some text modes, where <TAB> 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 <TAB> does, but in some text modes, where <TAB>
+ inserts a tab, `reindent-then-newline-and-indent' indents to the
+ column specified by `left-margin'.
- - Function: setcar cons-cell object
- This function stores OBJECT as the new CAR of CONS-CELL, replacing
- its previous CAR. It returns the value OBJECT. For example:
+\1f
+File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation
- (setq x '(1 2))
- => (1 2)
- (setcar x 4)
- => 4
- x
- => (4 2)
-
- When a cons cell is part of the shared structure of several lists,
-storing a new CAR into the cons changes one element of each of these
-lists. Here is an example:
-
- ;; Create two lists that are partly shared.
- (setq x1 '(a b c))
- => (a b c)
- (setq x2 (cons 'z (cdr x1)))
- => (z b c)
-
- ;; Replace the CAR of a shared link.
- (setcar (cdr x1) 'foo)
- => foo
- x1 ; Both lists are changed.
- => (a foo c)
- x2
- => (z foo c)
-
- ;; Replace the CAR of a link that is not shared.
- (setcar x1 'baz)
- => baz
- x1 ; Only one list is changed.
- => (baz foo c)
- x2
- => (z foo c)
-
- Here is a graphical depiction of the shared structure of the two
-lists in the variables `x1' and `x2', showing why replacing `b' changes
-them both:
-
- ___ ___ ___ ___ ___ ___
- x1---> |___|___|----> |___|___|--> |___|___|--> nil
- | --> | |
- | | | |
- --> a | --> b --> c
- |
- ___ ___ |
- x2--> |___|___|--
- |
- |
- --> z
-
- Here is an alternative form of box diagram, showing the same
-relationship:
-
- x1:
- -------------- -------------- --------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | o------->| b | o------->| c | nil |
- | | | -->| | | | | |
- -------------- | -------------- --------------
- |
- x2: |
- -------------- |
- | car | cdr | |
- | z | o----
- | | |
- --------------
-
-\1f
-File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
-
-Altering the CDR of a List
+Indenting an Entire Region
--------------------------
- The lowest-level primitive for modifying a CDR is `setcdr':
-
- - Function: setcdr cons-cell object
- This function stores OBJECT as the new CDR of CONS-CELL, replacing
- its previous CDR. It returns the value OBJECT.
-
- Here is an example of replacing the CDR of a list with a different
-list. All but the first element of the list are removed in favor of a
-different sequence of elements. The first element is unchanged,
-because it resides in the CAR of the list, and is not reached via the
-CDR.
-
- (setq x '(1 2 3))
- => (1 2 3)
- (setcdr x '(4))
- => (4)
- x
- => (1 4)
-
- You can delete elements from the middle of a list by altering the
-CDRs of the cons cells in the list. For example, here we delete the
-second element, `b', from the list `(a b c)', by changing the CDR of
-the first cell:
-
- (setq x1 '(a b c))
- => (a b c)
- (setcdr x1 (cdr (cdr x1)))
- => (c)
- x1
- => (a c)
-
- Here is the result in box notation:
-
- --------------------
- | |
- -------------- | -------------- | --------------
- | car | cdr | | | car | cdr | -->| car | cdr |
- | a | o----- | b | o-------->| c | nil |
- | | | | | | | | |
- -------------- -------------- --------------
-
-The second cons cell, which previously held the element `b', still
-exists and its CAR is still `b', but it no longer forms part of this
-list.
-
- It is equally easy to insert a new element by changing CDRs:
-
- (setq x1 '(a b c))
- => (a b c)
- (setcdr x1 (cons 'd (cdr x1)))
- => (d b c)
- x1
- => (a d b c)
-
- Here is this result in box notation:
-
- -------------- ------------- -------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | o | -->| b | o------->| c | nil |
- | | | | | | | | | | |
- --------- | -- | ------------- -------------
- | |
- ----- --------
- | |
- | --------------- |
- | | car | cdr | |
- -->| d | o------
- | | |
- ---------------
-
-\1f
-File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
-
-Functions that Rearrange Lists
-------------------------------
-
- Here are some functions that rearrange lists "destructively" by
-modifying the CDRs of their component cons cells. We call these
-functions "destructive" because they chew up the original lists passed
-to them as arguments, to produce a new list that is the returned value.
-
- See `delq', in *Note Sets And Lists::, for another function that
-modifies cons cells.
-
- - Function: nconc &rest lists
- This function returns a list containing all the elements of LISTS.
- Unlike `append' (*note Building Lists::), the LISTS are _not_
- copied. Instead, the last CDR of each of the LISTS is changed to
- refer to the following list. The last of the LISTS is not
- altered. For example:
-
- (setq x '(1 2 3))
- => (1 2 3)
- (nconc x '(4 5))
- => (1 2 3 4 5)
- x
- => (1 2 3 4 5)
-
- Since the last argument of `nconc' is not itself modified, it is
- reasonable to use a constant list, such as `'(4 5)', as in the
- above example. For the same reason, the last argument need not be
- a list:
-
- (setq x '(1 2 3))
- => (1 2 3)
- (nconc x 'z)
- => (1 2 3 . z)
- x
- => (1 2 3 . z)
-
- A common pitfall is to use a quoted constant list as a non-last
- argument to `nconc'. If you do this, your program will change
- each time you run it! Here is what happens:
-
- (defun add-foo (x) ; We want this function to add
- (nconc '(foo) x)) ; `foo' to the front of its arg.
-
- (symbol-function 'add-foo)
- => (lambda (x) (nconc (quote (foo)) x))
-
- (setq xx (add-foo '(1 2))) ; It seems to work.
- => (foo 1 2)
- (setq xy (add-foo '(3 4))) ; What happened?
- => (foo 1 2 3 4)
- (eq xx xy)
- => t
-
- (symbol-function 'add-foo)
- => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
-
- - Function: nreverse list
- This function reverses the order of the elements of LIST. Unlike
- `reverse', `nreverse' alters its argument by reversing the CDRs in
- the cons cells forming the list. The cons cell that used to be
- the last one in LIST becomes the first cell of the value.
-
- For example:
-
- (setq x '(1 2 3 4))
- => (1 2 3 4)
- x
- => (1 2 3 4)
- (nreverse x)
- => (4 3 2 1)
- ;; The cell that was first is now last.
- x
- => (1)
-
- To avoid confusion, we usually store the result of `nreverse' back
- in the same variable which held the original list:
-
- (setq x (nreverse x))
-
- Here is the `nreverse' of our favorite example, `(a b c)',
- presented graphically:
-
- Original list head: Reversed list:
- ------------- ------------- ------------
- | car | cdr | | car | cdr | | car | cdr |
- | a | nil |<-- | b | o |<-- | c | o |
- | | | | | | | | | | | | |
- ------------- | --------- | - | -------- | -
- | | | |
- ------------- ------------
-
- - Function: sort list predicate
- This function sorts LIST stably, though destructively, and returns
- the sorted list. It compares elements using PREDICATE. A stable
- sort is one in which elements with equal sort keys maintain their
- relative order before and after the sort. Stability is important
- when successive sorts are used to order elements according to
- different criteria.
-
- The argument PREDICATE must be a function that accepts two
- arguments. It is called with two elements of LIST. To get an
- increasing order sort, the PREDICATE should return `t' if the
- first element is "less than" the second, or `nil' if not.
-
- The destructive aspect of `sort' is that it rearranges the cons
- cells forming LIST by changing CDRs. A nondestructive sort
- function would create new cons cells to store the elements in their
- sorted order. If you wish to make a sorted copy without
- destroying the original, copy it first with `copy-sequence' and
- then sort.
-
- Sorting does not change the CARs of the cons cells in LIST; the
- cons cell that originally contained the element `a' in LIST still
- has `a' in its CAR after sorting, but it now appears in a
- different position in the list due to the change of CDRs. For
- example:
-
- (setq nums '(1 3 2 6 5 4 0))
- => (1 3 2 6 5 4 0)
- (sort nums '<)
- => (0 1 2 3 4 5 6)
- nums
- => (1 2 3 4 5 6)
-
- Note that the list in `nums' no longer contains 0; this is the same
- cons cell that it was before, but it is no longer the first one in
- the list. Don't assume a variable that formerly held the argument
- now holds the entire sorted list! Instead, save the result of
- `sort' and use that. Most often we store the result back into the
- variable that held the original list:
-
- (setq nums (sort nums '<))
-
- *Note Sorting::, for more functions that perform sorting. See
- `documentation' in *Note Accessing Documentation::, for a useful
- example of `sort'.
-
-\1f
-File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
-
-Using Lists as Sets
-===================
+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').
- A list can represent an unordered mathematical set--simply consider a
-value an element of a set if it appears in the list, and ignore the
-order of the list. To form the union of two sets, use `append' (as
-long as you don't mind having duplicate elements). Other useful
-functions for sets include `memq' and `delq', and their `equal'
-versions, `member' and `delete'.
-
- Common Lisp note: Common Lisp has functions `union' (which avoids
- duplicate elements) and `intersection' for set operations, but
- XEmacs Lisp does not have them. You can write them in Lisp if you
- wish.
-
- - Function: memq object list
- This function tests to see whether OBJECT is a member of LIST. If
- it is, `memq' returns a list starting with the first occurrence of
- OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
- says that it uses `eq' to compare OBJECT against the elements of
- the list. For example:
-
- (memq 'b '(a b c b a))
- => (b c b a)
- (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
- => nil
+\1f
+File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation
- - Function: delq object list
- This function destructively removes all elements `eq' to OBJECT
- from LIST. The letter `q' in `delq' says that it uses `eq' to
- compare OBJECT against the elements of the list, like `memq'.
-
- When `delq' deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
-
- (delq 'a '(a b c)) == (cdr '(a b c))
-
- When an element to be deleted appears in the middle of the list,
-removing it involves changing the CDRs (*note Setcdr::).
-
- (setq sample-list '(a b c (4)))
- => (a b c (4))
- (delq 'a sample-list)
- => (b c (4))
- sample-list
- => (a b c (4))
- (delq 'c sample-list)
- => (a b (4))
- sample-list
- => (a b (4))
-
- Note that `(delq 'c sample-list)' modifies `sample-list' to splice
-out the third element, but `(delq 'a sample-list)' does not splice
-anything--it just returns a shorter list. Don't assume that a variable
-which formerly held the argument LIST now has fewer elements, or that
-it still holds the original list! Instead, save the result of `delq'
-and use that. Most often we store the result back into the variable
-that held the original list:
-
- (setq flowers (delq 'rose flowers))
-
- In the following example, the `(4)' that `delq' attempts to match
-and the `(4)' in the `sample-list' are not `eq':
-
- (delq '(4) sample-list)
- => (a c (4))
-
- The following two functions are like `memq' and `delq' but use
-`equal' rather than `eq' to compare elements. They are new in Emacs 19.
-
- - Function: member object list
- The function `member' tests to see whether OBJECT is a member of
- LIST, comparing members with OBJECT using `equal'. If OBJECT is a
- member, `member' returns a list starting with its first occurrence
- in LIST. Otherwise, it returns `nil'.
-
- Compare this with `memq':
-
- (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
- => ((2))
- (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
- => nil
- ;; Two strings with the same contents are `equal'.
- (member "foo" '("foo" "bar"))
- => ("foo" "bar")
+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':
- - Function: delete object list
- This function destructively removes all elements `equal' to OBJECT
- from LIST. It is to `delq' as `member' is to `memq': it uses
- `equal' to compare elements with OBJECT, like `member'; when it
- finds an element that matches, it removes the element just as
- `delq' would. For example:
+ This line is indented twelve spaces.
+ The quick brown fox jum-!-ped.
- (delete '(2) '((2) (1) (2)))
- => '((1))
+ Evaluation of the expression `(indent-relative nil)' produces the
+ following:
- Common Lisp note: The functions `member' and `delete' in XEmacs
- Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
- versions do not use `equal' to compare elements.
+ This line is indented twelve spaces.
+ The quick brown fox jum -!-ped.
- See also the function `add-to-list', in *Note Setting Variables::,
-for another way to add an element to a list stored in a variable.
+ - 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.
\1f
-File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
+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 <TAB> 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.
-Association Lists
-=================
+\1f
+File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation
- An "association list", or "alist" for short, records a mapping from
-keys to values. It is a list of cons cells called "associations": the
-CAR of each cell is the "key", and the CDR is the "associated value".(1)
-
- Here is an example of an alist. The key `pine' is associated with
-the value `cones'; the key `oak' is associated with `acorns'; and the
-key `maple' is associated with `seeds'.
-
- '((pine . cones)
- (oak . acorns)
- (maple . seeds))
-
- The associated values in an alist may be any Lisp objects; so may the
-keys. For example, in the following alist, the symbol `a' is
-associated with the number `1', and the string `"b"' is associated with
-the _list_ `(2 3)', which is the CDR of the alist element:
-
- ((a . 1) ("b" 2 3))
-
- Sometimes it is better to design an alist to store the associated
-value in the CAR of the CDR of the element. Here is an example:
-
- '((rose red) (lily white) (buttercup yellow))
-
-Here we regard `red' as the value associated with `rose'. One
-advantage of this method is that you can store other related
-information--even a list of other items--in the CDR of the CDR. One
-disadvantage is that you cannot use `rassq' (see below) to find the
-element containing a given value. When neither of these considerations
-is important, the choice is a matter of taste, as long as you are
-consistent about it for any given alist.
-
- Note that the same alist shown above could be regarded as having the
-associated value in the CDR of the element; the value associated with
-`rose' would be the list `(red)'.
-
- Association lists are often used to record information that you might
-otherwise keep on a stack, since new associations may be added easily to
-the front of the list. When searching an association list for an
-association with a given key, the first one found is returned, if there
-is more than one.
-
- In XEmacs Lisp, it is _not_ an error if an element of an association
-list is not a cons cell. The alist search functions simply ignore such
-elements. Many other versions of Lisp signal errors in such cases.
-
- Note that property lists are similar to association lists in several
-respects. A property list behaves like an association list in which
-each key can occur only once. *Note Property Lists::, for a comparison
-of property lists and association lists.
-
- - Function: assoc key alist
- This function returns the first association for KEY in ALIST. It
- compares KEY against the alist elements using `equal' (*note
- Equality Predicates::). It returns `nil' if no association in
- ALIST has a CAR `equal' to KEY. For example:
-
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- => ((pine . cones) (oak . acorns) (maple . seeds))
- (assoc 'oak trees)
- => (oak . acorns)
- (cdr (assoc 'oak trees))
- => acorns
- (assoc 'birch trees)
- => nil
+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'.
- Here is another example, in which the keys and values are not
- symbols:
+\1f
+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'.
- (setq needles-per-cluster
- '((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine")))
+ 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 ----------
- (cdr (assoc 3 needles-per-cluster))
- => ("Pitch Pine")
- (cdr (assoc 2 needles-per-cluster))
- => ("Austrian Pine" "Red Pine")
-
- - Function: rassoc value alist
- This function returns the first association with value VALUE in
- ALIST. It returns `nil' if no association in ALIST has a CDR
- `equal' to VALUE.
-
- `rassoc' is like `assoc' except that it compares the CDR of each
- ALIST association instead of the CAR. You can think of this as
- "reverse `assoc'", finding the key for a given value.
-
- - Function: assq key alist
- This function is like `assoc' in that it returns the first
- association for KEY in ALIST, but it makes the comparison using
- `eq' instead of `equal'. `assq' returns `nil' if no association
- in ALIST has a CAR `eq' to KEY. This function is used more often
- than `assoc', since `eq' is faster than `equal' and most alists
- use symbols as keys. *Note Equality Predicates::.
-
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- => ((pine . cones) (oak . acorns) (maple . seeds))
- (assq 'pine trees)
- => (pine . cones)
-
- On the other hand, `assq' is not usually useful in alists where the
- keys may not be symbols:
-
- (setq leaves
- '(("simple leaves" . oak)
- ("compound leaves" . horsechestnut)))
+ (capitalize-region 1 44)
+ => nil
- (assq "simple leaves" leaves)
- => nil
- (assoc "simple leaves" leaves)
- => ("simple leaves" . oak)
+ ---------- Buffer: foo ----------
+ This Is The Contents Of The 5th Foo.
+ ---------- Buffer: foo ----------
- - Function: rassq value alist
- This function returns the first association with value VALUE in
- ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
- to VALUE.
+ - 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'.
- `rassq' is like `assq' except that it compares the CDR of each
- ALIST association instead of the CAR. You can think of this as
- "reverse `assq'", finding the key for a given value.
+ When `downcase-region' is called interactively, START and END are
+ point and the mark, with the smallest first.
- For example:
+ - 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'.
- (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-
- (rassq 'acorns trees)
- => (oak . acorns)
- (rassq 'spores trees)
- => 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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
+
+Substituting for a Character Code
+=================================
- Note that `rassq' cannot search for a value stored in the CAR of
- the CDR of an element:
+The following functions replace characters within a specified region
+based on their character codes.
- (setq colors '((rose red) (lily white) (buttercup yellow)))
+ - 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 ----------
- (rassq 'white colors)
+ (subst-char-in-region 1 20 ?i ?X)
=> nil
-
- In this case, the CDR of the association `(lily white)' is not the
- symbol `white', but rather the list `(white)'. This becomes
- clearer if the association is written in dotted pair notation:
-
- (lily white) == (lily . (white))
-
- - Function: remassoc key alist
- This function deletes by side effect any associations with key KEY
- in ALIST--i.e. it removes any elements from ALIST whose `car' is
- `equal' to KEY. The modified ALIST is returned.
-
- If the first member of ALIST has a `car' that is `equal' to KEY,
- there is no way to remove it by side effect; therefore, write
- `(setq foo (remassoc key foo))' to be sure of changing the value
- of `foo'.
-
- - Function: remassq key alist
- This function deletes by side effect any associations with key KEY
- in ALIST--i.e. it removes any elements from ALIST whose `car' is
- `eq' to KEY. The modified ALIST is returned.
-
- This function is exactly like `remassoc', but comparisons between
- KEY and keys in ALIST are done using `eq' instead of `equal'.
-
- - Function: remrassoc value alist
- This function deletes by side effect any associations with value
- VALUE in ALIST--i.e. it removes any elements from ALIST whose
- `cdr' is `equal' to VALUE. The modified ALIST is returned.
-
- If the first member of ALIST has a `car' that is `equal' to VALUE,
- there is no way to remove it by side effect; therefore, write
- `(setq foo (remassoc value foo))' to be sure of changing the value
- of `foo'.
-
- `remrassoc' is like `remassoc' except that it compares the CDR of
- each ALIST association instead of the CAR. You can think of this
- as "reverse `remassoc'", removing an association based on its
- value instead of its key.
-
- - Function: remrassq value alist
- This function deletes by side effect any associations with value
- VALUE in ALIST--i.e. it removes any elements from ALIST whose
- `cdr' is `eq' to VALUE. The modified ALIST is returned.
-
- This function is exactly like `remrassoc', but comparisons between
- VALUE and values in ALIST are done using `eq' instead of `equal'.
-
- - Function: copy-alist alist
- This function returns a two-level deep copy of ALIST: it creates a
- new copy of each association, so that you can alter the
- associations of the new alist without changing the old one.
-
- (setq needles-per-cluster
- '((2 . ("Austrian Pine" "Red Pine"))
- (3 . ("Pitch Pine"))
- (5 . ("White Pine"))))
- =>
- ((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
- (setq copy (copy-alist needles-per-cluster))
- =>
- ((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
+ ---------- 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 ----------
- (eq needles-per-cluster copy)
- => nil
- (equal needles-per-cluster copy)
- => t
- (eq (car needles-per-cluster) (car copy))
- => nil
- (cdr (car (cdr needles-per-cluster)))
- => ("Pitch Pine")
- (eq (cdr (car (cdr needles-per-cluster)))
- (cdr (car (cdr copy))))
- => t
+ (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 ----------
+
+\1f
+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.
- This example shows how `copy-alist' makes it possible to change
- the associations of one copy without affecting the other:
+\1f
+File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
+
+Transposition of Text
+=====================
- (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
- (cdr (assq 3 needles-per-cluster))
- => ("Pitch Pine")
+This subroutine is used by the transposition commands.
- ---------- Footnotes ----------
+ - 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.
- (1) This usage of "key" is not related to the term "key sequence";
-it means a value used to look up an item in a table. In this case, the
-table is the alist, and the alist associations are the items.
+ 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.
\1f
-File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
+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.
-Property Lists
-==============
+\1f
+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.
- A "property list" (or "plist") is another way of representing a
-mapping from keys to values. Instead of the list consisting of conses
-of a key and a value, the keys and values alternate as successive
-entries in the list. Thus, the association list
+ 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.
- ((a . 1) (b . 2) (c . 3))
+ `base64-encode-region' returns the length of the encoded text.
- has the equivalent property list form
+ ;; Encode the whole buffer in base64
+ (base64-encode-region (point-min) (point-max))
- (a 1 b 2 c 3)
+ The function can also be used interactively, in which case it
+ works on the currently active region.
- Property lists are used to represent the properties associated with
-various sorts of objects, such as symbols, strings, frames, etc. The
-convention is that property lists can be modified in-place, while
-association lists generally are not.
+ - Function: base64-encode-string string &optional no-line-break
+ This function encodes STRING to base64, and returns the encoded
+ string.
- Plists come in two varieties: "normal" plists, whose keys are
-compared with `eq', and "lax" plists, whose keys are compared with
-`equal',
+ 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.
- - Function: valid-plist-p plist
- Given a plist, this function returns non-`nil' if its format is
- correct. If it returns `nil', `check-valid-plist' will signal an
- error when given the plist; that means it's a malformed or circular
- plist or has non-symbols as keywords.
+ For Mule, the same considerations apply as for
+ `base64-encode-region'.
- - Function: check-valid-plist plist
- Given a plist, this function signals an error if there is anything
- wrong with it. This means that it's a malformed or circular plist.
+ (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
+
+\1f
+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:
-* Working With Normal Plists:: Functions for normal plists.
-* Working With Lax Plists:: Functions for lax plists.
-* Converting Plists To/From Alists:: Alist to plist and vice-versa.
+* 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::.
\1f
-File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
+File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching
-Working With Normal Plists
---------------------------
+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.
- - Function: plist-get plist property &optional default
- This function extracts a value from a property list. The function
- returns the value corresponding to the given PROPERTY, or DEFAULT
- if PROPERTY is not one of the properties on the list.
+ - 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).
- - Function: plist-put plist property value
- This function changes the value in PLIST of PROPERTY to VALUE. If
- PROPERTY is already a property on the list, its value is set to
- VALUE, otherwise the new PROPERTY VALUE pair is added. The new
- plist is returned; use `(setq x (plist-put x property value))' to
- be sure to use the new value. The PLIST is modified by side
- effects.
+ 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':
- - Function: plist-remprop plist property
- This function removes from PLIST the property PROPERTY and its
- value. The new plist is returned; use `(setq x (plist-remprop x
- property))' to be sure to use the new value. The PLIST is
- modified by side effects.
+ ---------- 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.
- - Function: plist-member plist property
- This function returns `t' if PROPERTY has a value specified in
- PLIST.
+\1f
+File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching
- In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
-non-`nil', then a property with a `nil' value is ignored or removed.
-This feature is a virus that has infected old Lisp implementations (and
-thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
-used except for backward compatibility.
+Regular Expressions
+===================
- - Function: plists-eq a b &optional nil-means-not-present
- This function returns non-`nil' if property lists A and B are `eq'
- (i.e. their values are `eq').
+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.
- - Function: plists-equal a b &optional nil-means-not-present
- This function returns non-`nil' if property lists A and B are
- `equal' (i.e. their values are `equal'; their keys are still
- compared using `eq').
+* Menu:
- - Function: canonicalize-plist plist &optional nil-means-not-present
- This function destructively removes any duplicate entries from a
- plist. In such cases, the first entry applies.
+* Syntax of Regexps:: Rules for writing regular expressions.
+* Regexp Example:: Illustrates regular expression syntax.
- The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
- return value may not be `eq' to the passed-in value, so make sure
- to `setq' the value back into where it came from.
+\1f
+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-"))
\1f
-File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
+File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
-Working With Lax Plists
------------------------
+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'.
- Recall that a "lax plist" is a property list whose keys are compared
-using `equal' instead of `eq'.
+ 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.
- - Function: lax-plist-get lax-plist property &optional default
- This function extracts a value from a lax property list. The
- function returns the value corresponding to the given PROPERTY, or
- DEFAULT if PROPERTY is not one of the properties on the list.
+ "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
- - Function: lax-plist-put lax-plist property value
- This function changes the value in LAX-PLIST of PROPERTY to VALUE.
+ In contrast, if you evaluate the variable `sentence-end', you will
+see the following:
- - Function: lax-plist-remprop lax-plist property
- This function removes from LAX-PLIST the property PROPERTY and its
- value. The new plist is returned; use `(setq x (lax-plist-remprop
- x property))' to be sure to use the new value. The LAX-PLIST is
- modified by side effects.
+ sentence-end
+ =>
+ "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
+ ]*"
- - Function: lax-plist-member lax-plist property
- This function returns `t' if PROPERTY has a value specified in
- LAX-PLIST.
+In this output, tab and newline appear as themselves.
- In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
-non-`nil', then a property with a `nil' value is ignored or removed.
-This feature is a virus that has infected old Lisp implementations (and
-thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
-used except for backward compatibility.
+ This regular expression contains four parts in succession and can be
+deciphered as follows:
- - Function: lax-plists-eq a b &optional nil-means-not-present
- This function returns non-`nil' if lax property lists A and B are
- `eq' (i.e. their values are `eq'; their keys are still compared
- using `equal').
+`[.?!]'
+ 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.
- - Function: lax-plists-equal a b &optional nil-means-not-present
- This function returns non-`nil' if lax property lists A and B are
- `equal' (i.e. their values are `equal').
+`[]\"')}]*'
+ 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.
- - Function: canonicalize-lax-plist lax-plist &optional
- nil-means-not-present
- This function destructively removes any duplicate entries from a
- lax plist. In such cases, the first entry applies.
+`\\($\\| $\\|\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.
- The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
- return value may not be `eq' to the passed-in value, so make sure
- to `setq' the value back into where it came from.
+`[ \t\n]*'
+ Finally, the last part of the pattern matches any additional
+ whitespace beyond the minimum needed to end a sentence.
\1f
-File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
+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
-Converting Plists To/From Alists
---------------------------------
+ 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.
- - Function: alist-to-plist alist
- This function converts association list ALIST into the equivalent
- property-list form. The plist is returned. This converts from
+ (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
+
+\1f
+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.
+
+\1f
+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'.
- ((a . 1) (b . 2) (c . 3))
+ - 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:
- into
+ * The "key bindings" are not commands, just symbols that are
+ meaningful to the functions that use this map.
- (a 1 b 2 c 3)
+ * 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."
- The original alist is not modified.
+ Here are the meaningful "bindings" for `query-replace-map'. Several
+of them are meaningful only for `query-replace' and friends.
- - Function: plist-to-alist plist
- This function converts property list PLIST into the equivalent
- association-list form. The alist is returned. This converts from
+`act'
+ Do take the action being considered--in other words, "yes."
- (a 1 b 2 c 3)
+`skip'
+ Do not take action for this question--in other words, "no."
- into
+`exit'
+ Answer this question "no," and give up on the entire series of
+ questions, assuming that the answers will be "no."
- ((a . 1) (b . 2) (c . 3))
+`act-and-exit'
+ Answer this question "yes," and give up on the entire series of
+ questions, assuming that subsequent answers will be "no."
- The original plist is not modified.
+`act-and-show'
+ Answer this question "yes," but show the results--don't advance yet
+ to the next question.
- The following two functions are equivalent to the preceding two
-except that they destructively modify their arguments, using cons cells
-from the original list to form the new list rather than allocating new
-cons cells.
+`automatic'
+ Answer this question and all subsequent questions in the series
+ with "yes," without further user interaction.
- - Function: destructive-alist-to-plist alist
- This function destructively converts association list ALIST into
- the equivalent property-list form. The plist is returned.
+`backup'
+ Move back to the previous place that a question was asked about.
- - Function: destructive-plist-to-alist plist
- This function destructively converts property list PLIST into the
- equivalent association-list form. The alist is returned.
+`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.
\1f
-File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
+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.
-Weak Lists
-==========
+* 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.
+
+\1f
+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 ----------
- A "weak list" is a special sort of list whose members are not counted
-as references for the purpose of garbage collection. This means that,
-for any object in the list, if there are no references to the object
-anywhere outside of the list (or other weak list or weak hash table),
-that object will disappear the next time a garbage collection happens.
-Weak lists can be useful for keeping track of things such as unobtrusive
-lists of another function's buffers or markers. When that function is
-done with the elements, they will automatically disappear from the list.
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)
- Weak lists are used internally, for example, to manage the list
-holding the children of an extent--an extent that is unused but has a
-parent will still be reclaimed, and will automatically be removed from
-its parent's list of children.
+\1f
+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.
- Weak lists are similar to weak hash tables (*note Weak Hash
-Tables::).
+\1f
+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)
+ => (#<marker at 9 in foo>
+ #<marker at 17 in foo>
+ #<marker at 13 in foo>
+ #<marker at 17 in foo>)
+
+ - 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'.
- - Function: weak-list-p object
- This function returns non-`nil' if OBJECT is a weak list.
+\1f
+File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
- Weak lists come in one of four types:
+Saving and Restoring the Match Data
+-----------------------------------
-`simple'
- Objects in the list disappear if not referenced outside of the
- list.
+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:
-`assoc'
- Objects in the list disappear if they are conses and either the
- car or the cdr of the cons is not referenced outside of the list.
+ (re-search-forward "The \\(cat \\)")
+ => 48
+ (foo) ; Perhaps `foo' does
+ ; more searching.
+ (match-end 0)
+ => 61 ; Unexpected result--not 48!
-`key-assoc'
- Objects in the list disappear if they are conses and the car is not
- referenced outside of the list.
+ You can save and restore the match data with `save-match-data':
-`value-assoc'
- Objects in the list disappear if they are conses and the cdr is not
- referenced outside of the list.
+ - Special Form: save-match-data body...
+ This special form executes BODY, saving and restoring the match
+ data around it.
- - Function: make-weak-list &optional type
- This function creates a new weak list of type TYPE. TYPE is a
- symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
- as described above) and defaults to `simple'.
+ 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:
- - Function: weak-list-type weak
- This function returns the type of the given weak-list object.
+ (let ((data (match-data)))
+ (unwind-protect
+ ... ; May change the original match data.
+ (set-match-data data)))
- - Function: weak-list-list weak
- This function returns the list contained in a weak-list object.
+ Emacs automatically saves and restores the match data when it runs
+process filter functions (*note Filter Functions::) and process
+sentinels (*note Sentinels::).
- - Function: set-weak-list-list weak new-list
- This function changes the list contained in a weak-list object.
+\1f
+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)'.
\1f
-File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
+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::.
-Sequences, Arrays, and Vectors
-******************************
+\1f
+File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
- Recall that the "sequence" type is the union of four other Lisp
-types: lists, vectors, bit vectors, and strings. In other words, any
-list is a sequence, any vector is a sequence, any bit vector is a
-sequence, and any string is a sequence. The common property that all
-sequences have is that each is an ordered collection of elements.
+Syntax Tables
+*************
- An "array" is a single primitive object that has a slot for each
-elements. All the elements are accessible in constant time, but the
-length of an existing array cannot be changed. Strings, vectors, and
-bit vectors are the three types of arrays.
+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.
- A list is a sequence of elements, but it is not a single primitive
-object; it is made of cons cells, one cell per element. Finding the
-Nth element requires looking through N cons cells, so elements farther
-from the beginning of the list take longer to access. But it is
-possible to add elements to the list, or remove elements.
+* Menu:
- The following diagram shows the relationship between these types:
+* 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.
- ___________________________________
- | |
- | Sequence |
- | ______ ______________________ |
- | | | | | |
- | | List | | Array | |
- | | | | ________ _______ | |
- | |______| | | | | | | |
- | | | Vector | | String| | |
- | | |________| |_______| | |
- | | __________________ | |
- | | | | | |
- | | | Bit Vector | | |
- | | |__________________| | |
- | |______________________| |
- |___________________________________|
+\1f
+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.
- The elements of vectors and lists may be any Lisp objects. The
-elements of strings are all characters. The elements of bit vectors
-are the numbers 0 and 1.
+\1f
+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:
-* Sequence Functions:: Functions that accept any kind of sequence.
-* Arrays:: Characteristics of arrays in XEmacs Lisp.
-* Array Functions:: Functions specifically for arrays.
-* Vectors:: Special characteristics of XEmacs Lisp vectors.
-* Vector Functions:: Functions specifically for vectors.
-* Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
-* Bit Vector Functions:: Functions specifically for bit vectors.
+* Syntax Class Table:: Table of syntax classes.
+* Syntax Flags:: Additional flags each character can have.
+
+\1f
+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 `@'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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"))))
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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))
+ #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 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!)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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))
+ => #<color-specifier 0x3da>
+
+ (specifier-specs sp)
+ => ((#<buffer "device.c"> (nil . "forest green"))
+ (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+ (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
+ (nil . "moccasin"))
+ (#<x-frame "VM" 0x4ac> (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 on "*scratch*" 0x4ad>
+ (window-frame (get-buffer-window "*scratch*"))
+ => #<x-frame "emacs" 0x4ac>
+ (specifier-instance sp (get-buffer-window "*scratch*"))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+
+ 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 `(#<x-frame "emacs" 0x4ac> . "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 `(#<x-frame "emacs" 0x4ac> . "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
+ => #<generic-specifier global=(nil) 0x4f5cb>
+
+ ;; 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
+ => #<generic-specifier global=(nil) 0x4f5cb>
+
+ ;; get the whole specification list
+ (specifier-specs foo)
+ => ((#<x-frame "Message" 0x1bd66> (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)
+ => ((#<x-frame "emacs" 0x28ec> (nil . baz))
+ (#<x-frame "Message" 0x1bd66> (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.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::).
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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).
projects / chise / xemacs-chise.git.1 / blobdiff