X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=info%2Flispref.info-6;h=ed9d8460d9bb328ea467803c00780e1c235cd05c;hp=1145cac0f0d760c487acb3b894974d9a2114e7e3;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=716cfba952c1dc0d2cf5c968971f3780ba728a89 diff --git a/info/lispref.info-6 b/info/lispref.info-6 index 1145cac..ed9d846 100644 --- a/info/lispref.info-6 +++ b/info/lispref.info-6 @@ -1,4 +1,4 @@ -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 @@ -50,1287 +50,6813 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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 -=========================== + +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. + +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, 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. + +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. - - -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::). + +File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text + +Sorting Text +============ + +The sorting functions described in this section all rearrange text in a +buffer. This is in contrast to the function `sort', which rearranges +the order of the elements of a list (*note Rearrangement::). The +values returned by these functions are not meaningful. + + - Function: sort-subr reverse nextrecfun endrecfun &optional + startkeyfun endkeyfun + This function is the general text-sorting routine that divides a + buffer into records and sorts them. Most of the commands in this + section use this function. + + To understand how `sort-subr' works, consider the whole accessible + portion of the buffer as being divided into disjoint pieces called + "sort records". The records may or may not be contiguous; they may + not overlap. A portion of each sort record (perhaps all of it) is + designated as the sort key. Sorting rearranges the records in + order by their sort keys. + + Usually, the records are rearranged in order of ascending sort key. + If the first argument to the `sort-subr' function, REVERSE, is + non-`nil', the sort records are rearranged in order of descending + sort key. + + The next four arguments to `sort-subr' are functions that are + called to move point across a sort record. They are called many + times from within `sort-subr'. + + 1. NEXTRECFUN is called with point at the end of a record. This + function moves point to the start of the next record. The + first record is assumed to start at the position of point + when `sort-subr' is called. Therefore, you should usually + move point to the beginning of the buffer before calling + `sort-subr'. + + This function can indicate there are no more sort records by + leaving point at the end of the buffer. + + 2. ENDRECFUN is called with point within a record. It moves + point to the end of the record. + + 3. STARTKEYFUN is called to move point from the start of a + record to the start of the sort key. This argument is + optional; if it is omitted, the whole record is the sort key. + If supplied, the function should either return a non-`nil' + value to be used as the sort key, or return `nil' to indicate + that the sort key is in the buffer starting at point. In the + latter case, ENDKEYFUN is called to find the end of the sort + key. + + 4. ENDKEYFUN is called to move point from the start of the sort + key to the end of the sort key. This argument is optional. + If STARTKEYFUN returns `nil' and this argument is omitted (or + `nil'), then the sort key extends to the end of the record. + There is no need for ENDKEYFUN if STARTKEYFUN returns a + non-`nil' value. + + As an example of `sort-subr', here is the complete function + definition for `sort-lines': + + ;; Note that the first two lines of doc string + ;; are effectively one line when viewed by a user. + (defun sort-lines (reverse start end) + "Sort lines in region alphabetically. + Called from a program, there are three arguments: + REVERSE (non-nil means reverse order), + and START and END (the region to sort)." + (interactive "P\nr") + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (sort-subr reverse + 'forward-line + 'end-of-line))) + + Here `forward-line' moves point to the start of the next record, + and `end-of-line' moves point to the end of record. We do not pass + the arguments STARTKEYFUN and ENDKEYFUN, because the entire record + is used as the sort key. + + The `sort-paragraphs' function is very much the same, except that + its `sort-subr' call looks like this: + + (sort-subr reverse + (function + (lambda () + (skip-chars-forward "\n \t\f"))) + 'forward-paragraph) + + - Command: sort-regexp-fields reverse record-regexp key-regexp start + end + This command sorts the region between START and END alphabetically + as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a + negative integer, then sorting is in reverse order. + + Alphabetical sorting means that two sort keys are compared by + comparing the first characters of each, the second characters of + each, and so on. If a mismatch is found, it means that the sort + keys are unequal; the sort key whose character is less at the + point of first mismatch is the lesser sort key. The individual + characters are compared according to their numerical values. + Since Emacs uses the ASCII character set, the ordering in that set + determines alphabetical order. + + The value of the RECORD-REGEXP argument specifies how to divide + the buffer into sort records. At the end of each record, a search + is done for this regular expression, and the text that matches it + is the next record. For example, the regular expression `^.+$', + which matches lines with at least one character besides a newline, + would make each such line into a sort record. *Note Regular + Expressions::, for a description of the syntax and meaning of + regular expressions. + + The value of the KEY-REGEXP argument specifies what part of each + record is the sort key. The KEY-REGEXP could match the whole + record, or only a part. In the latter case, the rest of the + record has no effect on the sorted order of records, but it is + carried along when the record moves to its new position. + + The KEY-REGEXP argument can refer to the text matched by a + subexpression of RECORD-REGEXP, or it can be a regular expression + on its own. + + If KEY-REGEXP is: + + `\DIGIT' + then the text matched by the DIGITth `\(...\)' parenthesis + grouping in RECORD-REGEXP is the sort key. + + `\&' + then the whole record is the sort key. + + a regular expression + then `sort-regexp-fields' searches for a match for the regular + expression within the record. If such a match is found, it + is the sort key. If there is no match for KEY-REGEXP within + a record then that record is ignored, which means its + position in the buffer is not changed. (The other records + may move around it.) + + For example, if you plan to sort all the lines in the region by the + first word on each line starting with the letter `f', you should + set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\'. The + resulting expression looks like this: + + (sort-regexp-fields nil "^.*$" "\\" + (region-beginning) + (region-end)) + + If you call `sort-regexp-fields' interactively, it prompts for + RECORD-REGEXP and KEY-REGEXP in the minibuffer. + + - Command: sort-lines reverse start end + This command alphabetically sorts lines in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-paragraphs reverse start end + This command alphabetically sorts paragraphs in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-pages reverse start end + This command alphabetically sorts pages in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-fields field start end + This command sorts lines in the region between START and END, + comparing them alphabetically by the FIELDth field of each line. + Fields are separated by whitespace and numbered starting from 1. + If FIELD is negative, sorting is by the -FIELDth field from the + end of the line. This command is useful for sorting tables. + + - Command: sort-numeric-fields field start end + This command sorts lines in the region between START and END, + comparing them numerically by the FIELDth field of each line. The + specified field must contain a number in each line of the region. + Fields are separated by whitespace and numbered starting from 1. + If FIELD is negative, sorting is by the -FIELDth field from the + end of the line. This command is useful for sorting tables. + + - Command: sort-columns reverse &optional start end + This command sorts the lines in the region between START and END, + comparing them alphabetically by a certain range of columns. The + column positions of START and END bound the range of columns to + sort on. + + If REVERSE is non-`nil', the sort is in reverse order. + + One unusual thing about this command is that the entire line + containing position START, and the entire line containing position + END, are included in the region sorted. + + Note that `sort-columns' uses the `sort' utility program, and so + cannot work properly on text containing tab characters. Use `M-x + `untabify'' to convert tabs to spaces before sorting. - (make-list 3 'pigs) - => (pigs pigs pigs) - (make-list 0 'pigs) - => nil + +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. - -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. + + +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.  -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' + +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 key +to indent properly for the language being edited. This section +describes the mechanism of the key and how to control it. The +functions in this section return unpredictable values. + + - Variable: indent-line-function + This variable's value is the function to be used by (and + various commands) to indent the current line. The command + `indent-according-to-mode' does no more than call this function. + + In Lisp mode, the value is the symbol `lisp-indent-line'; in C + mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In + Fundamental mode, Text mode, and many other modes with no standard + for indentation, the value is `indent-to-left-margin' (which is the + default value). + + - Command: indent-according-to-mode + This command calls the function in `indent-line-function' to + indent the current line in a way appropriate for the current major + mode. + + - Command: indent-for-tab-command &optional prefix-arg + This command calls the function in `indent-line-function' to indent + the current line; except that if that function is + `indent-to-left-margin', it calls `insert-tab' instead. (That is + a trivial command that inserts a tab character.) + + - Command: newline-and-indent + This function inserts a newline, then indents the new line (the one + following the newline just inserted) according to the major mode. + + It does indentation by calling the current `indent-line-function'. + In programming language modes, this is the same thing does, + but in some text modes, where inserts a tab, + `newline-and-indent' indents to the column specified by + `left-margin'. + + - Command: reindent-then-newline-and-indent + This command reindents the current line, inserts a newline at + point, and then reindents the new line (the one following the + newline just inserted). + + This command does indentation on both lines according to the + current major mode, by calling the current value of + `indent-line-function'. In programming language modes, this is + the same thing does, but in some text modes, where + inserts a tab, `reindent-then-newline-and-indent' indents to the + column specified by `left-margin'. - - Function: setcar cons object - This function stores OBJECT as the new CAR of CONS, replacing its - previous CAR. It returns the value OBJECT. For example: + +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---- - | | | - -------------- - - -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 object - This function stores OBJECT as the new CDR of CONS, 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------ - | | | - --------------- - - -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'. - - -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 + +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.  -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 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 -================= + +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: + +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. + + +File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text + +Text Properties +=============== + +Text properties are an alternative interface to extents (*note +Extents::), and are built on top of them. They are useful when you +want to view textual properties as being attached to the characters +themselves rather than to intervals of characters. The text property +interface is compatible with FSF Emacs. + + Each character position in a buffer or a string can have a "text +property list", much like the property list of a symbol (*note Property +Lists::). The properties belong to a particular character at a +particular place, such as, the letter `T' at the beginning of this +sentence or the first `o' in `foo'--if the same character occurs in two +different places, the two occurrences generally have different +properties. + + Each property has a name and a value. Both of these can be any Lisp +object, but the name is normally a symbol. The usual way to access the +property list is to specify a name and ask what value corresponds to it. + + Note that FSF Emacs also looks at the `category' property to find +defaults for text properties. We consider this too bogus to implement. + + Copying text between strings and buffers preserves the properties +along with the characters; this includes such diverse functions as +`substring', `insert', and `buffer-substring'. + +* Menu: + +* Examining Properties:: Looking at the properties of one character. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. +* Saving Properties:: Saving text properties in files, and reading + them back. + + +File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties + +Examining Text Properties +------------------------- + +The simplest way to examine text properties is to ask for the value of +a particular property of a particular character. For that, use +`get-text-property'. Use `text-properties-at' to get the entire +property list of a character. *Note Property Search::, for functions +to examine the properties of a number of characters at once. + + These functions handle both strings and buffers. (Keep in mind that +positions in a string start from 0, whereas positions in a buffer start +from 1.) + + - Function: get-text-property pos prop &optional object at-flag + This function returns the value of the PROP property of the + character after position POS in OBJECT (a buffer or string). The + argument OBJECT is optional and defaults to the current buffer. + + - Function: get-char-property pos prop &optional object at-flag + This function is like `get-text-property', except that it checks + all extents, not just text-property extents. + + + - Function: text-properties-at position &optional object + This function returns the entire property list of the character at + POSITION in the string or buffer OBJECT. If OBJECT is `nil', it + defaults to the current buffer. + + - Variable: default-text-properties + This variable holds a property list giving default values for text + properties. Whenever a character does not specify a value for a + property, the value stored in this list is used instead. Here is + an example: + + (setq default-text-properties '(foo 69)) + ;; Make sure character 1 has no properties of its own. + (set-text-properties 1 2 nil) + ;; What we get, when we ask, is the default value. + (get-text-property 1 'foo) + => 69 + + +File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties + +Changing Text Properties +------------------------ + +The primitives for changing properties apply to a specified range of +text. The function `set-text-properties' (see end of section) sets the +entire property list of the text in that range; more often, it is +useful to add, change, or delete just certain properties specified by +name. + + Since text properties are considered part of the buffer's contents, +and can affect how the buffer looks on the screen, any change in the +text properties is considered a buffer modification. Buffer text +property changes are undoable (*note Undo::). + + - Function: put-text-property start end prop value &optional object + This function sets the PROP property to VALUE for the text between + START and END in the string or buffer OBJECT. If OBJECT is `nil', + it defaults to the current buffer. + + - Function: add-text-properties start end props &optional object + This function modifies the text properties for the text between + START and END in the string or buffer OBJECT. If OBJECT is `nil', + it defaults to the current buffer. + + The argument PROPS specifies which properties to change. It + should have the form of a property list (*note Property Lists::): + a list whose elements include the property names followed + alternately by the corresponding values. + + The return value is `t' if the function actually changed some + property's value; `nil' otherwise (if PROPS is `nil' or its values + agree with those in the text). + + For example, here is how to set the `comment' and `face' + properties of a range of text: + + (add-text-properties START END + '(comment t face highlight)) + + - Function: remove-text-properties start end props &optional object + This function deletes specified text properties from the text + between START and END in the string or buffer OBJECT. If OBJECT + is `nil', it defaults to the current buffer. + + The argument PROPS specifies which properties to delete. It + should have the form of a property list (*note Property Lists::): + a list whose elements are property names alternating with + corresponding values. But only the names matter--the values that + accompany them are ignored. For example, here's how to remove the + `face' property. + + (remove-text-properties START END '(face nil)) + + The return value is `t' if the function actually changed some + property's value; `nil' otherwise (if PROPS is `nil' or if no + character in the specified text had any of those properties). + + - Function: set-text-properties start end props &optional object + This function completely replaces the text property list for the + text between START and END in the string or buffer OBJECT. If + OBJECT is `nil', it defaults to the current buffer. + + The argument PROPS is the new property list. It should be a list + whose elements are property names alternating with corresponding + values. + + After `set-text-properties' returns, all the characters in the + specified range have identical properties. + + If PROPS is `nil', the effect is to get rid of all properties from + the specified range of text. Here's an example: + + (set-text-properties START END nil) + + See also the function `buffer-substring-without-properties' (*note +Buffer Contents::) which copies text from the buffer but does not copy +its properties. + + +File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties + +Property Search Functions +------------------------- + +In typical use of text properties, most of the time several or many +consecutive characters have the same value for a property. Rather than +writing your programs to examine characters one by one, it is much +faster to process chunks of text that have the same property value. + + Here are functions you can use to do this. They use `eq' for +comparing property values. In all cases, OBJECT defaults to the +current buffer. + + For high performance, it's very important to use the LIMIT argument +to these functions, especially the ones that search for a single +property--otherwise, they may spend a long time scanning to the end of +the buffer, if the property you are interested in does not change. + + Remember that a position is always between two characters; the +position returned by these functions is between two characters with +different properties. + + - Function: next-property-change pos &optional object limit + The function scans the text forward from position POS in the + string or buffer OBJECT till it finds a change in some text + property, then returns the position of the change. In other + words, it returns the position of the first character beyond POS + whose properties are not identical to those of the character just + after POS. + + If LIMIT is non-`nil', then the scan ends at position LIMIT. If + there is no property change before that point, + `next-property-change' returns LIMIT. + + The value is `nil' if the properties remain unchanged all the way + to the end of OBJECT and LIMIT is `nil'. If the value is + non-`nil', it is a position greater than or equal to POS. The + value equals POS only when LIMIT equals POS. + + Here is an example of how to scan the buffer by chunks of text + within which all properties are constant: + + (while (not (eobp)) + (let ((plist (text-properties-at (point))) + (next-change + (or (next-property-change (point) (current-buffer)) + (point-max)))) + Process text from point to NEXT-CHANGE... + (goto-char next-change))) + + - Function: next-single-property-change pos prop &optional object limit + The function scans the text forward from position POS in the + string or buffer OBJECT till it finds a change in the PROP + property, then returns the position of the change. In other + words, it returns the position of the first character beyond POS + whose PROP property differs from that of the character just after + POS. + + If LIMIT is non-`nil', then the scan ends at position LIMIT. If + there is no property change before that point, + `next-single-property-change' returns LIMIT. + + The value is `nil' if the property remains unchanged all the way to + the end of OBJECT and LIMIT is `nil'. If the value is non-`nil', + it is a position greater than or equal to POS; it equals POS only + if LIMIT equals POS. + + - Function: previous-property-change pos &optional object limit + This is like `next-property-change', but scans backward from POS + instead of forward. If the value is non-`nil', it is a position + less than or equal to POS; it equals POS only if LIMIT equals POS. + + - Function: previous-single-property-change pos prop &optional object + limit + This is like `next-single-property-change', but scans backward from + POS instead of forward. If the value is non-`nil', it is a + position less than or equal to POS; it equals POS only if LIMIT + equals POS. + + - Function: text-property-any start end prop value &optional object + This function returns non-`nil' if at least one character between + START and END has a property PROP whose value is VALUE. More + precisely, it returns the position of the first such character. + Otherwise, it returns `nil'. + + The optional fifth argument, OBJECT, specifies the string or + buffer to scan. Positions are relative to OBJECT. The default + for OBJECT is the current buffer. + + - Function: text-property-not-all start end prop value &optional object + This function returns non-`nil' if at least one character between + START and END has a property PROP whose value differs from VALUE. + More precisely, it returns the position of the first such + character. Otherwise, it returns `nil'. + + The optional fifth argument, OBJECT, specifies the string or + buffer to scan. Positions are relative to OBJECT. The default + for OBJECT is the current buffer. + + +File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties + +Properties with Special Meanings +-------------------------------- + +The predefined properties are the same as those for extents. *Note +Extent Properties::. + + +File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties + +Saving Text Properties in Files +------------------------------- + +You can save text properties in files, and restore text properties when +inserting the files, using these two hooks: + + - Variable: write-region-annotate-functions + This variable's value is a list of functions for `write-region' to + run to encode text properties in some fashion as annotations to + the text being written in the file. *Note Writing to Files::. + + Each function in the list is called with two arguments: the start + and end of the region to be written. These functions should not + alter the contents of the buffer. Instead, they should return + lists indicating annotations to write in the file in addition to + the text in the buffer. + + Each function should return a list of elements of the form + `(POSITION . STRING)', where POSITION is an integer specifying the + relative position in the text to be written, and STRING is the + annotation to add there. + + Each list returned by one of these functions must be already + sorted in increasing order by POSITION. If there is more than one + function, `write-region' merges the lists destructively into one + sorted list. + + When `write-region' actually writes the text from the buffer to the + file, it intermixes the specified annotations at the corresponding + positions. All this takes place without modifying the buffer. + + - Variable: after-insert-file-functions + This variable holds a list of functions for `insert-file-contents' + to call after inserting a file's contents. These functions should + scan the inserted text for annotations, and convert them to the + text properties they stand for. + + Each function receives one argument, the length of the inserted + text; point indicates the start of that text. The function should + scan that text for annotations, delete them, and create the text + properties that the annotations specify. The function should + return the updated length of the inserted text, as it stands after + those changes. The value returned by one function becomes the + argument to the next function. + + These functions should always return with point at the beginning of + the inserted text. + + The intended use of `after-insert-file-functions' is for converting + some sort of textual annotations into actual text properties. But + other uses may be possible. + + We invite users to write Lisp programs to store and retrieve text +properties in files, using these hooks, and thus to experiment with +various data formats and find good ones. Eventually we hope users will +produce good, general extensions we can install in Emacs. + + We suggest not trying to handle arbitrary Lisp objects as property +names or property values--because a program that general is probably +difficult to write, and slow. Instead, choose a set of possible data +types that are reasonably flexible, and not too hard to encode. + + *Note Format Conversion::, for a related feature. + + +File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text + +Substituting for a Character Code +================================= - 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 ---------- + + +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: + +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.  -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 -============== + +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 + + +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::.  -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 prop &optional default - This function extracts a value from a property list. The function - returns the value corresponding to the given PROP, or DEFAULT if - PROP 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 prop val - This function changes the value in PLIST of PROP to VAL. If PROP - is already a property on the list, its value is set to VAL, - otherwise the new PROP VAL pair is added. The new plist is - returned; use `(setq x (plist-put x prop val))' 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 prop - This function removes from PLIST the property PROP and its value. - The new plist is returned; use `(setq x (plist-remprop x prop - val))' 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 prop - This function returns `t' if PROP has a value specified in PLIST. + +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. + +File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions + +Syntax of Regular Expressions +----------------------------- + +Regular expressions have a syntax in which a few characters are special +constructs and the rest are "ordinary". An ordinary character is a +simple regular expression that matches that character and nothing else. +The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and +`\'; no new special characters will be defined in the future. Any +other character appearing in a regular expression is ordinary, unless a +`\' precedes it. + + For example, `f' is not a special character, so it is ordinary, and +therefore `f' is a regular expression that matches the string `f' and +no other string. (It does _not_ match the string `ff'.) Likewise, `o' +is a regular expression that matches only `o'. + + Any two regular expressions A and B can be concatenated. The result +is a regular expression that matches a string if A matches some amount +of the beginning of that string and B matches the rest of the string. + + As a simple example, we can concatenate the regular expressions `f' +and `o' to get the regular expression `fo', which matches only the +string `fo'. Still trivial. To do something more powerful, you need +to use one of the special characters. Here is a list of them: + +`. (Period)' + is a special character that matches any single character except a + newline. Using concatenation, we can make regular expressions + like `a.b', which matches any three-character string that begins + with `a' and ends with `b'. + +`*' + is not a construct by itself; it is a quantifying suffix operator + that means to repeat the preceding regular expression as many + times as possible. In `fo*', the `*' applies to the `o', so `fo*' + matches one `f' followed by any number of `o's. The case of zero + `o's is allowed: `fo*' does match `f'. + + `*' always applies to the _smallest_ possible preceding + expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. + + The matcher processes a `*' construct by matching, immediately, as + many repetitions as can be found; it is "greedy". Then it + continues with the rest of the pattern. If that fails, + backtracking occurs, discarding some of the matches of the + `*'-modified construct in case that makes it possible to match the + rest of the pattern. For example, in matching `ca*ar' against the + string `caaar', the `a*' first tries to match all three `a's; but + the rest of the pattern is `ar' and there is only `r' left to + match, so this try fails. The next alternative is for `a*' to + match only two `a's. With this choice, the rest of the regexp + matches successfully. + + Nested repetition operators can be extremely slow if they specify + backtracking loops. For example, it could take hours for the + regular expression `\(x+y*\)*a' to match the sequence + `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because + Emacs must try each imaginable way of grouping the 35 `x''s before + concluding that none of them can work. To make sure your regular + expressions run fast, check nested repetitions carefully. + +`+' + is a quantifying suffix operator similar to `*' except that the + preceding expression must match at least once. It is also + "greedy". So, for example, `ca+r' matches the strings `car' and + `caaaar' but not the string `cr', whereas `ca*r' matches all three + strings. + +`?' + is a quantifying suffix operator similar to `*', except that the + preceding expression can match either once or not at all. For + example, `ca?r' matches `car' or `cr', but does not match anything + else. + +`*?' + works just like `*', except that rather than matching the longest + match, it matches the shortest match. `*?' is known as a + "non-greedy" quantifier, a regexp construct borrowed from Perl. + + This construct is very useful for when you want to match the text + inside a pair of delimiters. For instance, `/\*.*?\*/' will match + C comments in a string. This could not easily be achieved without + the use of a non-greedy quantifier. + + This construct has not been available prior to XEmacs 20.4. It is + not available in FSF Emacs. + +`+?' + is the non-greedy version of `+'. + +`??' + is the non-greedy version of `?'. + +`\{n,m\}' + serves as an interval quantifier, analogous to `*' or `+', but + specifies that the expression must match at least N times, but no + more than M times. This syntax is supported by most Unix regexp + utilities, and has been introduced to XEmacs for the version 20.3. + + Unfortunately, the non-greedy version of this quantifier does not + exist currently, although it does in Perl. + +`[ ... ]' + `[' begins a "character set", which is terminated by a `]'. In + the simplest case, the characters between the two brackets form + the set. Thus, `[ad]' matches either one `a' or one `d', and + `[ad]*' matches any string composed of just `a's and `d's + (including the empty string), from which it follows that `c[ad]*r' + matches `cr', `car', `cdr', `caddaar', etc. + + The usual regular expression special characters are not special + inside a character set. A completely different set of special + characters exists inside character sets: `]', `-' and `^'. + + `-' is used for ranges of characters. To write a range, write two + characters with a `-' between them. Thus, `[a-z]' matches any + lower case letter. Ranges may be intermixed freely with individual + characters, as in `[a-z$%.]', which matches any lower case letter + or `$', `%', or a period. + + To include a `]' in a character set, make it the first character. + For example, `[]a]' matches `]' or `a'. To include a `-', write + `-' as the first character in the set, or put it immediately after + a range. (You can replace one individual character C with the + range `C-C' to make a place to put the `-'.) There is no way to + write a set containing just `-' and `]'. + + To include `^' in a set, put it anywhere but at the beginning of + the set. + +`[^ ... ]' + `[^' begins a "complement character set", which matches any + character except the ones specified. Thus, `[^a-z0-9A-Z]' matches + all characters _except_ letters and digits. + + `^' is not special in a character set unless it is the first + character. The character following the `^' is treated as if it + were first (thus, `-' and `]' are not special there). + + Note that a complement character set can match a newline, unless + newline is mentioned as one of the characters not to match. + +`^' + is a special character that matches the empty string, but only at + the beginning of a line in the text being matched. Otherwise it + fails to match anything. Thus, `^foo' matches a `foo' that occurs + at the beginning of a line. + + When matching a string instead of a buffer, `^' matches at the + beginning of the string or after a newline character `\n'. + +`$' + is similar to `^' but matches only at the end of a line. Thus, + `x+$' matches a string of one `x' or more at the end of a line. + + When matching a string instead of a buffer, `$' matches at the end + of the string or before a newline character `\n'. + +`\' + has two functions: it quotes the special characters (including + `\'), and it introduces additional special constructs. + + Because `\' quotes special characters, `\$' is a regular + expression that matches only `$', and `\[' is a regular expression + that matches only `[', and so on. + + Note that `\' also has special meaning in the read syntax of Lisp + strings (*note String Type::), and must be quoted with `\'. For + example, the regular expression that matches the `\' character is + `\\'. To write a Lisp string that contains the characters `\\', + Lisp syntax requires you to quote each `\' with another `\'. + Therefore, the read syntax for a regular expression matching `\' + is `"\\\\"'. + + *Please note:* For historical compatibility, special characters are +treated as ordinary ones if they are in contexts where their special +meanings make no sense. For example, `*foo' treats `*' as ordinary +since there is no preceding expression on which the `*' can act. It is +poor practice to depend on this behavior; quote the special character +anyway, regardless of where it appears. + + For the most part, `\' followed by any character matches only that +character. However, there are several exceptions: characters that, +when preceded by `\', are special constructs. Such characters are +always ordinary when encountered on their own. Here is a table of `\' +constructs: + +`\|' + specifies an alternative. Two regular expressions A and B with + `\|' in between form an expression that matches anything that + either A or B matches. + + Thus, `foo\|bar' matches either `foo' or `bar' but no other string. + + `\|' applies to the largest possible surrounding expressions. + Only a surrounding `\( ... \)' grouping can limit the grouping + power of `\|'. + + Full backtracking capability exists to handle multiple uses of + `\|'. + +`\( ... \)' + is a grouping construct that serves three purposes: + + 1. To enclose a set of `\|' alternatives for other operations. + Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. + + 2. To enclose an expression for a suffix operator such as `*' to + act on. Thus, `ba\(na\)*' matches `bananana', etc., with any + (zero or more) number of `na' strings. + + 3. To record a matched substring for future reference. + + This last application is not a consequence of the idea of a + parenthetical grouping; it is a separate feature that happens to be + assigned as a second meaning to the same `\( ... \)' construct + because there is no conflict in practice between the two meanings. + Here is an explanation of this feature: + +`\DIGIT' + matches the same text that matched the DIGITth occurrence of a `\( + ... \)' construct. + + In other words, after the end of a `\( ... \)' construct. the + matcher remembers the beginning and end of the text matched by that + construct. Then, later on in the regular expression, you can use + `\' followed by DIGIT to match that same text, whatever it may + have been. + + The strings matching the first nine `\( ... \)' constructs + appearing in a regular expression are assigned numbers 1 through 9 + in the order that the open parentheses appear in the regular + expression. So you can use `\1' through `\9' to refer to the text + matched by the corresponding `\( ... \)' constructs. + + For example, `\(.*\)\1' matches any newline-free string that is + composed of two identical halves. The `\(.*\)' matches the first + half, which may be anything, but the `\1' that follows must match + the same exact text. + +`\(?: ... \)' + is called a "shy" grouping operator, and it is used just like `\( + ... \)', except that it does not cause the matched substring to be + recorded for future reference. + + This is useful when you need a lot of grouping `\( ... \)' + constructs, but only want to remember one or two - or if you have + more than nine groupings and need to use backreferences to refer to + the groupings at the end. + + Using `\(?: ... \)' rather than `\( ... \)' when you don't need + the captured substrings ought to speed up your programs some, + since it shortens the code path followed by the regular expression + engine, as well as the amount of memory allocation and string + copying it must do. The actual performance gain to be observed + has not been measured or quantified as of this writing. + + The shy grouping operator has been borrowed from Perl, and has not + been available prior to XEmacs 20.3, nor is it available in FSF + Emacs. + +`\w' + matches any word-constituent character. The editor syntax table + determines which characters these are. *Note Syntax Tables::. + +`\W' + matches any character that is not a word constituent. + +`\sCODE' + matches any character whose syntax is CODE. Here CODE is a + character that represents a syntax code: thus, `w' for word + constituent, `-' for whitespace, `(' for open parenthesis, etc. + *Note Syntax Tables::, for a list of syntax codes and the + characters that stand for them. + +`\SCODE' + matches any character whose syntax is not CODE. + + The following regular expression constructs match the empty +string--that is, they don't use up any characters--but whether they +match depends on the context. + +`\`' + matches the empty string, but only at the beginning of the buffer + or string being matched against. + +`\'' + matches the empty string, but only at the end of the buffer or + string being matched against. + +`\=' + matches the empty string, but only at point. (This construct is + not defined when matching against a string.) + +`\b' + matches the empty string, but only at the beginning or end of a + word. Thus, `\bfoo\b' matches any occurrence of `foo' as a + separate word. `\bballs?\b' matches `ball' or `balls' as a + separate word. + +`\B' + matches the empty string, but _not_ at the beginning or end of a + word. + +`\<' + matches the empty string, but only at the beginning of a word. + +`\>' + matches the empty string, but only at the end of a word. + + Not every string is a valid regular expression. For example, a +string with unbalanced square brackets is invalid (with a few +exceptions, such as `[]]'), and so is a string that ends with a single +`\'. If an invalid regular expression is passed to any of the search +functions, an `invalid-regexp' error is signaled. + + - Function: regexp-quote string + This function returns a regular expression string that matches + exactly STRING and nothing else. This allows you to request an + exact string match when calling a function that wants a regular + expression. + + (regexp-quote "^The cat$") + => "\\^The cat\\$" + + One use of `regexp-quote' is to combine an exact string match with + context described as a regular expression. For example, this + searches for the string that is the value of `string', surrounded + by whitespace: + + (re-search-forward + (concat "\\s-" (regexp-quote string) "\\s-"))  -File: lispref.info, Node: 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 prop &optional default - This function extracts a value from a lax property list. The - function returns the value corresponding to the given PROP, or - DEFAULT if PROP is not one of the properties on the list. + "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" - - Function: lax-plist-put lax-plist prop val - This function changes the value in LAX-PLIST of PROP to VAL. + In contrast, if you evaluate the variable `sentence-end', you will +see the following: - - Function: lax-plist-remprop lax-plist prop - This function removes from LAX-PLIST the property PROP and its - value. The new plist is returned; use `(setq x (lax-plist-remprop - x prop val))' to be sure to use the new value. The LAX-PLIST is - modified by side effects. + sentence-end + => + "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[ + ]*" - - Function: lax-plist-member lax-plist prop - This function returns `t' if PROP 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.  -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 + + +File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching + +POSIX Regular Expression Searching +================================== + +The usual regular expression functions do backtracking when necessary +to handle the `\|' and repetition constructs, but they continue this +only until they find _some_ match. Then they succeed and report the +first match found. + + This section describes alternative search functions which perform the +full backtracking specified by the POSIX standard for regular expression +matching. They continue backtracking until they have tried all +possibilities and found all matches, so they can report the longest +match, as required by POSIX. This is much slower, so use these +functions only when you really need the longest match. + + In Emacs versions prior to 19.29, these functions did not exist, and +the functions described above implemented full POSIX backtracking. + + - Command: posix-search-forward regexp &optional limit noerror count + buffer + This is like `re-search-forward' except that it performs the full + backtracking specified by the POSIX standard for regular expression + matching. + + - Command: posix-search-backward regexp &optional limit noerror count + buffer + This is like `re-search-backward' except that it performs the full + backtracking specified by the POSIX standard for regular expression + matching. + + - Function: posix-looking-at regexp &optional buffer + This is like `looking-at' except that it performs the full + backtracking specified by the POSIX standard for regular expression + matching. + + - Function: posix-string-match regexp string &optional start buffer + This is like `string-match' except that it performs the full + backtracking specified by the POSIX standard for regular expression + matching. + + Optional arg BUFFER controls how case folding is done (according + to the value of `case-fold-search' in BUFFER and BUFFER's case + tables) and defaults to the current buffer. + + +File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching + +Search and Replace +================== + + - Function: perform-replace from-string replacements query-flag + regexp-flag delimited-flag &optional repeat-count map + This function is the guts of `query-replace' and related commands. + It searches for occurrences of FROM-STRING and replaces some or + all of them. If QUERY-FLAG is `nil', it replaces all occurrences; + otherwise, it asks the user what to do about each one. + + If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a + regular expression; otherwise, it must match literally. If + DELIMITED-FLAG is non-`nil', then only replacements surrounded by + word boundaries are considered. + + The argument REPLACEMENTS specifies what to replace occurrences + with. If it is a string, that string is used. It can also be a + list of strings, to be used in cyclic order. + + If REPEAT-COUNT is non-`nil', it should be an integer. Then it + specifies how many times to use each of the strings in the + REPLACEMENTS list before advancing cyclicly to the next one. + + Normally, the keymap `query-replace-map' defines the possible user + responses for queries. The argument MAP, if non-`nil', is a + keymap to use instead of `query-replace-map'. - ((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.  -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. + + +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. + +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::). + +File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data + +Accessing the Entire Match Data +------------------------------- + +The functions `match-data' and `set-match-data' read or write the +entire match data, all at once. + + - Function: match-data &optional integers reuse + This function returns a newly constructed list containing all the + information on what text the last search matched. Element zero is + the position of the beginning of the match for the whole + expression; element one is the position of the end of the match + for the expression. The next two elements are the positions of + the beginning and end of the match for the first subexpression, + and so on. In general, element number 2N corresponds to + `(match-beginning N)'; and element number 2N + 1 corresponds to + `(match-end N)'. + + All the elements are markers or `nil' if matching was done on a + buffer, and all are integers or `nil' if matching was done on a + string with `string-match'. However, if the optional first + argument INTEGERS is non-`nil', always use integers (rather than + markers) to represent buffer positions. + + If the optional second argument REUSE is a list, reuse it as part + of the value. If REUSE is long enough to hold all the values, and + if INTEGERS is non-`nil', no new lisp objects are created. + + As always, there must be no possibility of intervening searches + between the call to a search function and the call to `match-data' + that is intended to access the match data for that search. + + (match-data) + => (# + # + # + #) + + - Function: set-match-data match-list + This function sets the match data from the elements of MATCH-LIST, + which should be a list that was the value of a previous call to + `match-data'. + + If MATCH-LIST refers to a buffer that doesn't exist, you don't get + an error; that sets the match data in a meaningless but harmless + way. + + `store-match-data' is an alias for `set-match-data'. - - Function: weak-list-p object - This function returns non-`nil' if OBJECT is a weak list. + +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. + +File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching + +Searching and Case +================== + +By default, searches in Emacs ignore the case of the text they are +searching through; if you specify searching for `FOO', then `Foo' or +`foo' is also considered a match. Regexps, and in particular character +sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'. + + If you do not want this feature, set the variable `case-fold-search' +to `nil'. Then all letters must match exactly, including case. This +is a buffer-local variable; altering the variable affects only the +current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you +may change the value of `default-case-fold-search', which is the +default value of `case-fold-search' for buffers that do not override it. + + Note that the user-level incremental search feature handles case +distinctions differently. When given a lower case letter, it looks for +a match of either case, but when given an upper case letter, it looks +for an upper case letter only. But this has nothing to do with the +searching functions Lisp functions use. + + - User Option: case-replace + This variable determines whether the replacement functions should + preserve case. If the variable is `nil', that means to use the + replacement text verbatim. A non-`nil' value means to convert the + case of the replacement text according to the text being replaced. + + The function `replace-match' is where this variable actually has + its effect. *Note Replacing Match::. + + - User Option: case-fold-search + This buffer-local variable determines whether searches should + ignore case. If the variable is `nil' they do not ignore case; + otherwise they do ignore case. + + - Variable: default-case-fold-search + The value of this variable is the default value for + `case-fold-search' in buffers that do not override it. This is the + same as `(default-value 'case-fold-search)'.  -File: lispref.info, Node: 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 -****************************** + +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 | | | - | | |__________________| | | - | |______________________| | - |___________________________________| + +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. + +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. + + +File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors + +Table of Syntax Classes +----------------------- + +Here is a table of syntax classes, the characters that stand for them, +their meanings, and examples of their use. + + - Syntax class: whitespace character + "Whitespace characters" (designated with `-') separate symbols and + words from each other. Typically, whitespace characters have no + other syntactic significance, and multiple whitespace characters + are syntactically equivalent to a single one. Space, tab, newline + and formfeed are almost always classified as whitespace. (The + designator ` ' is accepted for backwards compatibility with older + versions of XEmacs, but is deprecated. It is invalid in GNU + Emacs.) + + - Syntax class: word constituent + "Word constituents" (designated with `w') are parts of normal + English words and are typically used in variable and command names + in programs. All upper- and lower-case letters, and the digits, + are typically word constituents. + + - Syntax class: symbol constituent + "Symbol constituents" (designated with `_') are the extra + characters that are used in variable and command names along with + word constituents. For example, the symbol constituents class is + used in Lisp mode to indicate that certain characters may be part + of symbol names even though they are not part of English words. + These characters are `$&*+-_<>'. In standard C, the only + non-word-constituent character that is valid in symbols is + underscore (`_'). + + - Syntax class: punctuation character + "Punctuation characters" (`.') are those characters that are used + as punctuation in English, or are used in some way in a programming + language to separate symbols from one another. Most programming + language modes, including Emacs Lisp mode, have no characters in + this class since the few characters that are not symbol or word + constituents all have other uses. + + - Syntax class: open parenthesis character + - Syntax class: close parenthesis character + Open and close "parenthesis characters" are characters used in + dissimilar pairs to surround sentences or expressions. Such a + grouping is begun with an open parenthesis character and + terminated with a close. Each open parenthesis character matches + a particular close parenthesis character, and vice versa. + Normally, XEmacs indicates momentarily the matching open + parenthesis when you insert a close parenthesis. *Note Blinking::. + + The class of open parentheses is designated with `(', and that of + close parentheses with `)'. + + In English text, and in C code, the parenthesis pairs are `()', + `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and + vectors (`()' and `[]') are classified as parenthesis characters. + + - Syntax class: string quote + "String quote characters" (designated with `"') are used in many + languages, including Lisp and C, to delimit string constants. The + same string quote character appears at the beginning and the end + of a string. Such quoted strings do not nest. + + The parsing facilities of XEmacs consider a string as a single + token. The usual syntactic meanings of the characters in the + string are suppressed. + + The Lisp modes have two string quote characters: double-quote (`"') + and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is + used in Common Lisp. C also has two string quote characters: + double-quote for strings, and single-quote (`'') for character + constants. + + English text has no string quote characters because English is not + a programming language. Although quotation marks are used in + English, we do not want them to turn off the usual syntactic + properties of other characters in the quotation. + + - Syntax class: escape + An "escape character" (designated with `\') starts an escape + sequence such as is used in C string and character constants. The + character `\' belongs to this class in both C and Lisp. (In C, it + is used thus only inside strings, but it turns out to cause no + trouble to treat it this way throughout C code.) + + Characters in this class count as part of words if + `words-include-escapes' is non-`nil'. *Note Word Motion::. + + - Syntax class: character quote + A "character quote character" (designated with `/') quotes the + following character so that it loses its normal syntactic meaning. + This differs from an escape character in that only the character + immediately following is ever affected. + + Characters in this class count as part of words if + `words-include-escapes' is non-`nil'. *Note Word Motion::. + + This class is used for backslash in TeX mode. + + - Syntax class: paired delimiter + "Paired delimiter characters" (designated with `$') are like + string quote characters except that the syntactic properties of the + characters between the delimiters are not suppressed. Only TeX + mode uses a paired delimiter presently--the `$' that both enters + and leaves math mode. + + - Syntax class: expression prefix + An "expression prefix operator" (designated with `'') is used for + syntactic operators that are part of an expression if they appear + next to one. These characters in Lisp include the apostrophe, `'' + (used for quoting), the comma, `,' (used in macros), and `#' (used + in the read syntax for certain data types). + + - Syntax class: comment starter + - Syntax class: comment ender + The "comment starter" and "comment ender" characters are used in + various languages to delimit comments. These classes are + designated with `<' and `>', respectively. + + English text has no comment characters. In Lisp, the semicolon + (`;') starts a comment and a newline or formfeed ends one. + + - Syntax class: inherit + This syntax class does not specify a syntax. It says to look in + the standard syntax table to find the syntax of this character. + The designator for this syntax code is `@'. + + +File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors + +Syntax Flags +------------ + +In addition to the classes, entries for characters in a syntax table +can include flags. There are eleven possible flags, represented by the +digits `1'-`8', and the lowercase letters `a', `b', and `p'. + + All the flags except `p' are used to describe comment delimiters. +The digit flags indicate that a character can _also_ be part of a +multi-character comment sequence, in addition to the syntactic +properties associated with its character class. The flags must be +independent of the class and each other for the sake of characters such +as `*' in C mode, which is a punctuation character, _and_ the second +character of a start-of-comment sequence (`/*'), _and_ the first +character of an end-of-comment sequence (`*/'). + + Emacs supports two comment styles simultaneously in any one syntax +table. This is for the sake of C++. Each style of comment syntax has +its own comment-start sequence and its own comment-end sequence. Each +comment must stick to one style or the other; thus, if it starts with +the comment-start sequence of style "b", it must also end with the +comment-end sequence of style "b". + + As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary +comment-start sequences and two arbitrary comment-end sequences. (Thus +the need for 8 flags.) GNU Emacs restricts the comment-start sequences +to start with the same character, XEmacs does not. This means that for +two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses +the digit flags `5'-`8'. + + A one character comment-end sequence applies to the "b" style if its +first character has the `b' flag set; otherwise, it applies to the "a" +style. The `a' flag is optional. These flags have no effect on +non-comment characters; two-character styles are determined by the +digit flags. + + The flags for a character C are: + + * `1' means C is the start of a two-character comment-start sequence + of style "a". + + * `2' means C is the second character of such a sequence. + + * `3' means C is the start of a two-character comment-end sequence + of style "a". + + * `4' means C is the second character of such a sequence. + + * `5' means C is the start of a two-character comment-start sequence + of style "b". + + * `6' means C is the second character of such a sequence. + + * `7' means C is the start of a two-character comment-end sequence + of style "b". + + * `8' means C is the second character of such a sequence. + + * `a' means that C as a comment delimiter belongs to the default "a" + comment style. (This flag is optional.) + + * `b' means that C as a comment delimiter belongs to the alternate + "b" comment style. + + * `p' identifies an additional "prefix character" for Lisp syntax. + These characters are treated as whitespace when they appear between + expressions. When they appear within an expression, they are + handled according to their usual syntax codes. + + The function `backward-prefix-chars' moves back over these + characters, as well as over characters whose primary syntax class + is prefix (`''). *Note Motion and Syntax::. + + Lisp (as you would expect) has a simple comment syntax. + +`;' + `<' + +newline + `>' + + Note that no flags are used. This defines two comment-delimiting +sequences: + +`;' + This is a single-character comment-start sequence because the + syntax class is `<'. + +newline + This is a single character comment-end sequence because the syntax + class is `>' and the `b' flag is not set. + + C++ (again, as you would expect) has a baroque, overrich, and +excessively complex comment syntax. + +`/' + `1456' + +`*' + `23' + +newline + `>b' + + Note that the "b" style mixes one-character and two-character +sequences. The table above defines four comment-delimiting sequences: + +`/*' + This is a comment-start sequence for "a" style because the `1' + flag is set on `/' and the `2' flag is set on `*'. + +`//' + This is a comment-start sequence for "b" style because both the `5' + and the `6' flags are set on `/'. + +`*/' + This is a comment-end sequence for "a" style because the `3' flag + is set on `*' and the `4' flag is set on `/'. + +newline + This is a comment-end sequence for "b" style, because the newline + character has the `b' flag. + + +File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables + +Syntax Table Functions +====================== + +In this section we describe functions for creating, accessing and +altering syntax tables. + + - Function: make-syntax-table &optional oldtable + This function creates a new syntax table. Character codes 0 + through 31 and 128 through 255 are set up to inherit from the + standard syntax table. The other character codes are set up by + copying what the standard syntax table says about them. + + Most major mode syntax tables are created in this way. + + - Function: copy-syntax-table &optional syntax-table + This function constructs a copy of SYNTAX-TABLE and returns it. + If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy + of the current syntax table. Otherwise, an error is signaled if + SYNTAX-TABLE is not a syntax table. + + - Command: modify-syntax-entry char-range syntax-descriptor &optional + syntax-table + This function sets the syntax entry for CHAR-RANGE according to + SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a + range of characters, as used with `put-char-table'. The syntax is + changed only for SYNTAX-TABLE, which defaults to the current + buffer's syntax table, and not in any other syntax table. The + argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a + string beginning with a class designator character, and optionally + containing a matching character and flags as well. *Note Syntax + Descriptors::. + + This function always returns `nil'. The old syntax information in + the table for CHAR-RANGE is discarded. + + An error is signaled if the first character of the syntax + descriptor is not one of the twelve syntax class designator + characters. + + Examples: + + ;; Put the space character in class whitespace. + (modify-syntax-entry ?\ " ") + => nil + + ;; Make `$' an open parenthesis character, + ;; with `^' as its matching close. + (modify-syntax-entry ?$ "(^") + => nil + + ;; Make `^' a close parenthesis character, + ;; with `$' as its matching open. + (modify-syntax-entry ?^ ")$") + => nil + + ;; Make `/' a punctuation character, + ;; the first character of a start-comment sequence, + ;; and the second character of an end-comment sequence. + ;; This is used in C mode. + (modify-syntax-entry ?/ ". 14") + => nil + + - Function: char-syntax character &optional syntax-table + This function returns the syntax class of CHARACTER, represented + by its mnemonic designator character. This _only_ returns the + class, not any matching parenthesis or flags. + + An error is signaled if CHARACTER is not a character. + + The characters that correspond to various syntax codes are listed + in the documentation of `modify-syntax-entry'. + + Optional second argument SYNTAX-TABLE is the syntax table to be + used, and defaults to the current buffer's syntax table. + + The following examples apply to C mode. The first example shows + that the syntax class of space is whitespace (represented by a + space). The second example shows that the syntax of `/' is + punctuation. This does not show the fact that it is also part of + comment-start and -end sequences. The third example shows that + open parenthesis is in the class of open parentheses. This does + not show the fact that it has a matching character, `)'. + + (char-to-string (char-syntax ?\ )) + => " " + + (char-to-string (char-syntax ?/)) + => "." + + (char-to-string (char-syntax ?\()) + => "(" + + - Function: set-syntax-table syntax-table &optional buffer + This function makes SYNTAX-TABLE the syntax table for BUFFER, which + defaults to the current buffer if omitted. It returns + SYNTAX-TABLE. + + - Function: syntax-table &optional buffer + This function returns the syntax table for BUFFER, which defaults + to the current buffer if omitted. + + +File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables + +Motion and Syntax +================= + +This section describes functions for moving across characters in +certain syntax classes. None of these functions exists in Emacs +version 18 or earlier. + + - Function: skip-syntax-forward syntaxes &optional limit buffer + This function moves point forward across characters having syntax + classes mentioned in SYNTAXES. It stops when it encounters the + end of the buffer, or position LIMIT (if specified), or a + character it is not supposed to skip. Optional argument BUFFER + defaults to the current buffer if omitted. + + - Function: skip-syntax-backward syntaxes &optional limit buffer + This function moves point backward across characters whose syntax + classes are mentioned in SYNTAXES. It stops when it encounters + the beginning of the buffer, or position LIMIT (if specified), or a + character it is not supposed to skip. Optional argument BUFFER + defaults to the current buffer if omitted. + + + - Function: backward-prefix-chars &optional buffer + This function moves point backward over any number of characters + with expression prefix syntax. This includes both characters in + the expression prefix syntax class, and characters with the `p' + flag. Optional argument BUFFER defaults to the current buffer if + omitted. + + +File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables + +Parsing Balanced Expressions +============================ + +Here are several functions for parsing and scanning balanced +expressions, also known as "sexps", in which parentheses match in +pairs. The syntax table controls the interpretation of characters, so +these functions can be used for Lisp expressions when in Lisp mode and +for C expressions when in C mode. *Note List Motion::, for convenient +higher-level functions for moving over balanced expressions. + + - Function: parse-partial-sexp start limit &optional target-depth + stop-before state stop-comment buffer + This function parses a sexp in the current buffer starting at + START, not scanning past LIMIT. It stops at position LIMIT or + when certain criteria described below are met, and sets point to + the location where parsing stops. It returns a value describing + the status of the parse at the point where it stops. + + If STATE is `nil', START is assumed to be at the top level of + parenthesis structure, such as the beginning of a function + definition. Alternatively, you might wish to resume parsing in the + middle of the structure. To do this, you must provide a STATE + argument that describes the initial status of parsing. + + If the third argument TARGET-DEPTH is non-`nil', parsing stops if + the depth in parentheses becomes equal to TARGET-DEPTH. The depth + starts at 0, or at whatever is given in STATE. + + If the fourth argument STOP-BEFORE is non-`nil', parsing stops + when it comes to any character that starts a sexp. If + STOP-COMMENT is non-`nil', parsing stops when it comes to the + start of a comment. + + The fifth argument STATE is an eight-element list of the same form + as the value of this function, described below. The return value + of one call may be used to initialize the state of the parse on + another call to `parse-partial-sexp'. + + The result is a list of eight elements describing the final state + of the parse: + + 0. The depth in parentheses, counting from 0. + + 1. The character position of the start of the innermost + parenthetical grouping containing the stopping point; `nil' + if none. + + 2. The character position of the start of the last complete + subexpression terminated; `nil' if none. + + 3. Non-`nil' if inside a string. More precisely, this is the + character that will terminate the string. + + 4. `t' if inside a comment (of either style). + + 5. `t' if point is just after a quote character. + + 6. The minimum parenthesis depth encountered during this scan. + + 7. `t' if inside a comment of style "b". + + Elements 0, 3, 4, 5 and 7 are significant in the argument STATE. + + This function is most often used to compute indentation for + languages that have nested parentheses. + + - Function: scan-lists from count depth &optional buffer noerror + This function scans forward COUNT balanced parenthetical groupings + from character number FROM. It returns the character position + where the scan stops. + + If DEPTH is nonzero, parenthesis depth counting begins from that + value. The only candidates for stopping are places where the + depth in parentheses becomes zero; `scan-lists' counts COUNT such + places and then stops. Thus, a positive value for DEPTH means go + out DEPTH levels of parenthesis. + + Scanning ignores comments if `parse-sexp-ignore-comments' is + non-`nil'. + + If the scan reaches the beginning or end of the buffer (or its + accessible portion), and the depth is not zero, an error is + signaled. If the depth is zero but the count is not used up, + `nil' is returned. + + If optional arg BUFFER is non-`nil', scanning occurs in that + buffer instead of in the current buffer. + + If optional arg NOERROR is non-`nil', `scan-lists' will return + `nil' instead of signalling an error. + + - Function: scan-sexps from count &optional buffer noerror + This function scans forward COUNT sexps from character position + FROM. It returns the character position where the scan stops. + + Scanning ignores comments if `parse-sexp-ignore-comments' is + non-`nil'. + + If the scan reaches the beginning or end of (the accessible part + of) the buffer in the middle of a parenthetical grouping, an error + is signaled. If it reaches the beginning or end between groupings + but before count is used up, `nil' is returned. + + If optional arg BUFFER is non-`nil', scanning occurs in that + buffer instead of in the current buffer. + + If optional arg NOERROR is non-`nil', `scan-sexps' will return nil + instead of signalling an error. + + - Variable: parse-sexp-ignore-comments + If the value is non-`nil', then comments are treated as whitespace + by the functions in this section and by `forward-sexp'. + + In older Emacs versions, this feature worked only when the comment + terminator is something like `*/', and appears only to end a + comment. In languages where newlines terminate comments, it was + necessary make this variable `nil', since not every newline is the + end of a comment. This limitation no longer exists. + + You can use `forward-comment' to move forward or backward over one +comment or several comments. + + - Function: forward-comment &optional count buffer + This function moves point forward across COUNT comments (backward, + if COUNT is negative). If it finds anything other than a comment + or whitespace, it stops, leaving point at the place where it + stopped. It also stops after satisfying COUNT. COUNT defaults to + `1'. + + Optional argument BUFFER defaults to the current buffer. + + To move forward over all comments and whitespace following point, use +`(forward-comment (buffer-size))'. `(buffer-size)' is a good argument +to use, because the number of comments in the buffer cannot exceed that +many. + + +File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables + +Some Standard Syntax Tables +=========================== + +Most of the major modes in XEmacs have their own syntax tables. Here +are several of them: + + - Function: standard-syntax-table + This function returns the standard syntax table, which is the + syntax table used in Fundamental mode. + + - Variable: text-mode-syntax-table + The value of this variable is the syntax table used in Text mode. + + - Variable: c-mode-syntax-table + The value of this variable is the syntax table for C-mode buffers. + + - Variable: emacs-lisp-mode-syntax-table + The value of this variable is the syntax table used in Emacs Lisp + mode by editing commands. (It has no effect on the Lisp `read' + function.) + + +File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables + +Syntax Table Internals +====================== + +Each element of a syntax table is an integer that encodes the syntax of +one character: the syntax class, possible matching character, and +flags. Lisp programs don't usually work with the elements directly; the +Lisp-level syntax table functions usually work with syntax descriptors +(*note Syntax Descriptors::). + + The low 8 bits of each element of a syntax table indicate the syntax +class. + +Integer + Class + +0 + whitespace + +1 + punctuation + +2 + word + +3 + symbol + +4 + open parenthesis + +5 + close parenthesis + +6 + expression prefix + +7 + string quote + +8 + paired delimiter + +9 + escape + +10 + character quote + +11 + comment-start + +12 + comment-end + +13 + inherit + + The next 8 bits are the matching opposite parenthesis (if the +character has parenthesis syntax); otherwise, they are not meaningful. +The next 6 bits are the flags. + + +File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top + +Abbrevs And Abbrev Expansion +**************************** + +An abbreviation or "abbrev" is a string of characters that may be +expanded to a longer string. The user can insert the abbrev string and +find it replaced automatically with the expansion of the abbrev. This +saves typing. + + The set of abbrevs currently in effect is recorded in an "abbrev +table". Each buffer has a local abbrev table, but normally all buffers +in the same major mode share one abbrev table. There is also a global +abbrev table. Normally both are used. + + An abbrev table is represented as an obarray containing a symbol for +each abbreviation. The symbol's name is the abbreviation; its value is +the expansion; its function definition is the hook function to do the +expansion (*note Defining Abbrevs::); its property list cell contains +the use count, the number of times the abbreviation has been expanded. +Because these symbols are not interned in the usual obarray, they will +never appear as the result of reading a Lisp expression; in fact, +normally they are never used except by the code that handles abbrevs. +Therefore, it is safe to use them in an extremely nonstandard way. +*Note Creating Symbols::. + + For the user-level commands for abbrevs, see *Note Abbrev Mode: +(xemacs)Abbrevs. + +* Menu: + +* Abbrev Mode:: Setting up XEmacs for abbreviation. +* Tables: Abbrev Tables. Creating and working with abbrev tables. +* Defining Abbrevs:: Specifying abbreviations and their expansions. +* Files: Abbrev Files. Saving abbrevs in files. +* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. +* Standard Abbrev Tables:: Abbrev tables used by various major modes. + + +File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs + +Setting Up Abbrev Mode +====================== + +Abbrev mode is a minor mode controlled by the value of the variable +`abbrev-mode'. + + - Variable: abbrev-mode + A non-`nil' value of this variable turns on the automatic expansion + of abbrevs when their abbreviations are inserted into a buffer. + If the value is `nil', abbrevs may be defined, but they are not + expanded automatically. + + This variable automatically becomes local when set in any fashion. + + - Variable: default-abbrev-mode + This is the value of `abbrev-mode' for buffers that do not + override it. This is the same as `(default-value 'abbrev-mode)'. + + +File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs + +Abbrev Tables +============= + +This section describes how to create and manipulate abbrev tables. + + - Function: make-abbrev-table + This function creates and returns a new, empty abbrev table--an + obarray containing no symbols. It is a vector filled with zeros. + + - Function: clear-abbrev-table table + This function undefines all the abbrevs in abbrev table TABLE, + leaving it empty. The function returns `nil'. + + - Function: define-abbrev-table table-name definitions + This function defines TABLE-NAME (a symbol) as an abbrev table + name, i.e., as a variable whose value is an abbrev table. It + defines abbrevs in the table according to DEFINITIONS, a list of + elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The + value is always `nil'. + + - Variable: abbrev-table-name-list + This is a list of symbols whose values are abbrev tables. + `define-abbrev-table' adds the new abbrev table name to this list. + + - Function: insert-abbrev-table-description name &optional human + This function inserts before point a description of the abbrev + table named NAME. The argument NAME is a symbol whose value is an + abbrev table. The value is always `nil'. + + If HUMAN is non-`nil', the description is human-oriented. + Otherwise the description is a Lisp expression--a call to + `define-abbrev-table' that would define NAME exactly as it is + currently defined. + + +File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs + +Defining Abbrevs +================ + +These functions define an abbrev in a specified abbrev table. +`define-abbrev' is the low-level basic function, while `add-abbrev' is +used by commands that ask for information from the user. + + - Function: add-abbrev table type arg + This function adds an abbreviation to abbrev table TABLE based on + information from the user. The argument TYPE is a string + describing in English the kind of abbrev this will be (typically, + `"global"' or `"mode-specific"'); this is used in prompting the + user. The argument ARG is the number of words in the expansion. + + The return value is the symbol that internally represents the new + abbrev, or `nil' if the user declines to confirm redefining an + existing abbrev. + + - Function: define-abbrev table name &optional expansion hook count + This function defines an abbrev in TABLE named NAME, to expand to + EXPANSION, and call HOOK. The return value is an uninterned + symbol that represents the abbrev inside XEmacs; its name is NAME. + + The argument NAME should be a string. The argument EXPANSION + should be a string, or `nil' to undefine the abbrev. + + The argument HOOK is a function or `nil'. If HOOK is non-`nil', + then it is called with no arguments after the abbrev is replaced + with EXPANSION; point is located at the end of EXPANSION when HOOK + is called. + + The use count of the abbrev is initialized to zero. + + - User Option: only-global-abbrevs + If this variable is non-`nil', it means that the user plans to use + global abbrevs only. This tells the commands that define + mode-specific abbrevs to define global ones instead. This + variable does not alter the behavior of the functions in this + section; it is examined by their callers. + + +File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs + +Saving Abbrevs in Files +======================= + +A file of saved abbrev definitions is actually a file of Lisp code. +The abbrevs are saved in the form of a Lisp program to define the same +abbrev tables with the same contents. Therefore, you can load the file +with `load' (*note How Programs Do Loading::). However, the function +`quietly-read-abbrev-file' is provided as a more convenient interface. + + User-level facilities such as `save-some-buffers' can save abbrevs +in a file automatically, under the control of variables described here. + + - User Option: abbrev-file-name + This is the default file name for reading and saving abbrevs. + + - Function: quietly-read-abbrev-file &optional filename + This function reads abbrev definitions from a file named FILENAME, + previously written with `write-abbrev-file'. If FILENAME is + `nil', the file specified in `abbrev-file-name' is used. + `save-abbrevs' is set to `t' so that changes will be saved. + + This function does not display any messages. It returns `nil'. + + - User Option: save-abbrevs + A non-`nil' value for `save-abbrev' means that XEmacs should save + abbrevs when files are saved. `abbrev-file-name' specifies the + file to save the abbrevs in. + + - Variable: abbrevs-changed + This variable is set non-`nil' by defining or altering any + abbrevs. This serves as a flag for various XEmacs commands to + offer to save your abbrevs. + + - Command: write-abbrev-file filename + Save all abbrev definitions, in all abbrev tables, in the file + FILENAME, in the form of a Lisp program that when loaded will + define the same abbrevs. This function returns `nil'. + + +File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs + +Looking Up and Expanding Abbreviations +====================================== + +Abbrevs are usually expanded by commands for interactive use, including +`self-insert-command'. This section describes the subroutines used in +writing such functions, as well as the variables they use for +communication. + + - Function: abbrev-symbol abbrev &optional table + This function returns the symbol representing the abbrev named + ABBREV. The value returned is `nil' if that abbrev is not + defined. The optional second argument TABLE is the abbrev table + to look it up in. If TABLE is `nil', this function tries first + the current buffer's local abbrev table, and second the global + abbrev table. + + - Function: abbrev-expansion abbrev &optional table + This function returns the string that ABBREV would expand into (as + defined by the abbrev tables used for the current buffer). The + optional argument TABLE specifies the abbrev table to use, as in + `abbrev-symbol'. + + - Command: expand-abbrev + This command expands the abbrev before point, if any. If point + does not follow an abbrev, this command does nothing. The command + returns `t' if it did expansion, `nil' otherwise. + + - Command: abbrev-prefix-mark &optional arg + Mark current point as the beginning of an abbrev. The next call to + `expand-abbrev' will use the text from here to point (where it is + then) as the abbrev to expand, rather than using the previous word + as usual. + + - User Option: abbrev-all-caps + When this is set non-`nil', an abbrev entered entirely in upper + case is expanded using all upper case. Otherwise, an abbrev + entered entirely in upper case is expanded by capitalizing each + word of the expansion. + + - Variable: abbrev-start-location + This is the buffer position for `expand-abbrev' to use as the start + of the next abbrev to be expanded. (`nil' means use the word + before point instead.) `abbrev-start-location' is set to `nil' + each time `expand-abbrev' is called. This variable is also set by + `abbrev-prefix-mark'. + + - Variable: abbrev-start-location-buffer + The value of this variable is the buffer for which + `abbrev-start-location' has been set. Trying to expand an abbrev + in any other buffer clears `abbrev-start-location'. This variable + is set by `abbrev-prefix-mark'. + + - Variable: last-abbrev + This is the `abbrev-symbol' of the last abbrev expanded. This + information is left by `expand-abbrev' for the sake of the + `unexpand-abbrev' command. + + - Variable: last-abbrev-location + This is the location of the last abbrev expanded. This contains + information left by `expand-abbrev' for the sake of the + `unexpand-abbrev' command. + + - Variable: last-abbrev-text + This is the exact expansion text of the last abbrev expanded, + after case conversion (if any). Its value is `nil' if the abbrev + has already been unexpanded. This contains information left by + `expand-abbrev' for the sake of the `unexpand-abbrev' command. + + - Variable: pre-abbrev-expand-hook + This is a normal hook whose functions are executed, in sequence, + just before any expansion of an abbrev. *Note Hooks::. Since it + is a normal hook, the hook functions receive no arguments. + However, they can find the abbrev to be expanded by looking in the + buffer before point. + + The following sample code shows a simple use of +`pre-abbrev-expand-hook'. If the user terminates an abbrev with a +punctuation character, the hook function asks for confirmation. Thus, +this hook allows the user to decide whether to expand the abbrev, and +aborts expansion if it is not confirmed. + + (add-hook 'pre-abbrev-expand-hook 'query-if-not-space) + + ;; This is the function invoked by `pre-abbrev-expand-hook'. + + ;; If the user terminated the abbrev with a space, the function does + ;; nothing (that is, it returns so that the abbrev can expand). If the + ;; user entered some other character, this function asks whether + ;; expansion should continue. + + ;; If the user answers the prompt with `y', the function returns + ;; `nil' (because of the `not' function), but that is + ;; acceptable; the return value has no effect on expansion. + + (defun query-if-not-space () + (if (/= ?\ (preceding-char)) + (if (not (y-or-n-p "Do you want to expand this abbrev? ")) + (error "Not expanding this abbrev")))) + + +File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs + +Standard Abbrev Tables +====================== + +Here we list the variables that hold the abbrev tables for the +preloaded major modes of XEmacs. + + - Variable: global-abbrev-table + This is the abbrev table for mode-independent abbrevs. The abbrevs + defined in it apply to all buffers. Each buffer may also have a + local abbrev table, whose abbrev definitions take precedence over + those in the global table. + + - Variable: local-abbrev-table + The value of this buffer-local variable is the (mode-specific) + abbreviation table of the current buffer. + + - Variable: fundamental-mode-abbrev-table + This is the local abbrev table used in Fundamental mode; in other + words, it is the local abbrev table in all buffers in Fundamental + mode. + + - Variable: text-mode-abbrev-table + This is the local abbrev table used in Text mode. + + - Variable: c-mode-abbrev-table + This is the local abbrev table used in C mode. + + - Variable: lisp-mode-abbrev-table + This is the local abbrev table used in Lisp mode and Emacs Lisp + mode. + + +File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top + +Extents +******* + +An "extent" is a region of text (a start position and an end position) +that is displayed in a particular face and can have certain other +properties such as being read-only. Extents can overlap each other. +XEmacs efficiently handles buffers with large numbers of extents in +them. + + - Function: extentp object + This returns `t' if OBJECT is an extent. + +* Menu: + +* Intro to Extents:: Extents are regions over a buffer or string. +* Creating and Modifying Extents:: + Basic extent functions. +* Extent Endpoints:: Accessing and setting the bounds of an extent. +* Finding Extents:: Determining which extents are in an object. +* Mapping Over Extents:: More sophisticated functions for extent scanning. +* Extent Properties:: Extents have built-in and user-definable properties. +* Detached Extents:: Extents that are not in a buffer. +* Extent Parents:: Inheriting properties from another extent. +* Duplicable Extents:: Extents can be marked to be copied into strings. +* Extents and Events:: Extents can interact with the keyboard and mouse. +* Atomic Extents:: Treating a block of text as a single entity. + + +File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents + +Introduction to Extents +======================= + +An extent is a region of text within a buffer or string that has +certain properties associated with it. The properties of an extent +primarily affect the way the text contained in the extent is displayed. +Extents can freely overlap each other in a buffer or string. Extents +are invisible to functions that merely examine the text of a buffer or +string. + + _Please note:_ An alternative way to add properties to a buffer or +string is to use text properties. *Note Text Properties::. + + An extent is logically a Lisp object consisting of a start position, +an end position, a buffer or string to which these positions refer, and +a property list. As text is inserted into a buffer, the start and end +positions of the extent are automatically adjusted as necessary to keep +the extent referring to the same text in the buffer. If text is +inserted at the boundary of an extent, the extent's `start-open' and +`end-open' properties control whether the text is included as part of +the extent. If the text bounded by an extent is deleted, the extent +becomes "detached"; its start and end positions are no longer +meaningful, but it maintains all its other properties and can later be +reinserted into a buffer. (None of these considerations apply to +strings, because text cannot be inserted into or deleted from a string.) + + Each extent has a face or list of faces associated with it, which +controls the way in which the text bounded by the extent is displayed. +If an extent's face is `nil' or its properties are partially undefined, +the corresponding properties from the default face for the frame is +used. If two or more extents overlap, or if a list of more than one +face is specified for a particular extent, the corresponding faces are +merged to determine the text's displayed properties. Every extent has +a "priority" that determines which face takes precedence if the faces +conflict. (If two extents have the same priority, the one that comes +later in the display order takes precedence. *Note display order: +Extent Endpoints.) Higher-numbered priority values correspond to a +higher priority, and priority values can be negative. Every extent is +created with a priority of 0, but this can be changed with +`set-extent-priority'. Within a single extent with a list of faces, +faces earlier in the list have a higher priority than faces later in +the list. + + Extents can be set to respond specially to key and mouse events +within the extent. An extent's `keymap' property controls the effect of +key and mouse strokes within the extent's text, and the `mouse-face' +property controls whether the extent is highlighted when the mouse moves +over it. *Note Extents and Events::. + + An extent can optionally have a "begin-glyph" or "end-glyph" +associated with it. A begin-glyph or end-glyph is a pixmap or string +that will be displayed either at the start or end of an extent or in the +margin of the line that the start or end of the extent lies in, +depending on the extent's layout policy. Begin-glyphs and end-glyphs +are used to implement annotations, and you should use the annotation API +functions in preference to the lower-level extent functions. For more +information, *Note Annotations::. + + If an extent has its `detachable' property set, it will become +"detached" (i.e. no longer in the buffer) when all its text is deleted. +Otherwise, it will simply shrink down to zero-length and sit in the +same place in the buffer. By default, the `detachable' property is set +on newly-created extents. *Note Detached Extents::. + + If an extent has its `duplicable' property set, it will be +remembered when a string is created from text bounded by the extent. +When the string is re-inserted into a buffer, the extent will also be +re-inserted. This mechanism is used in the kill, yank, and undo +commands. *Note Duplicable Extents::. + + +File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents + +Creating and Modifying Extents +============================== + + - Function: make-extent from to &optional buffer-or-string + This function makes an extent for the range [FROM, TO) in + BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults + to the current buffer. Insertions at point TO will be outside of + the extent; insertions at FROM will be inside the extent, causing + the extent to grow (*note Extent Endpoints::). This is the same + way that markers behave. The extent is initially detached if both + FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults + to `nil', meaning the extent is in no buffer or string (*note + Detached Extents::). + + - Function: delete-extent extent + This function removes EXTENT from its buffer and destroys it. + This does not modify the buffer's text, only its display + properties. The extent cannot be used thereafter. To remove an + extent in such a way that it can be re-inserted later, use + `detach-extent'. *Note Detached Extents::. + + - Function: extent-object extent + This function returns the buffer or string that EXTENT is in. If + the return value is `nil', this means that the extent is detached; + however, a detached extent will not necessarily return a value of + `nil'. + + - Function: extent-live-p object + This function returns `t' if OBJECT is an extent that has not been + deleted, and `nil' otherwise. + + +File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents + +Extent Endpoints +================ + +Every extent has a start position and an end position, and logically +affects the characters between those positions. Normally the start and +end positions must both be valid positions in the extent's buffer or +string. However, both endpoints can be `nil', meaning the extent is +detached. *Note Detached Extents::. + + Whether the extent overlaps its endpoints is governed by its +`start-open' and `end-open' properties. Insertion of a character at a +closed endpoint will expand the extent to include that character; +insertion at an open endpoint will not. Similarly, functions such as +`extent-at' that scan over all extents overlapping a particular +position will include extents with a closed endpoint at that position, +but not extents with an open endpoint. + + Note that the `start-closed' and `end-closed' properties are +equivalent to `start-open' and `end-open' with the opposite sense. + + Both endpoints can be equal, in which case the extent includes no +characters but still exists in the buffer or string. Zero-length +extents are used to represent annotations (*note Annotations::) and can +be used as a more powerful form of a marker. Deletion of all the +characters in an extent may or may not result in a zero-length extent; +this depends on the `detachable' property (*note Detached Extents::). +Insertion at the position of a zero-length extent expands the extent if +both endpoints are closed; goes before the extent if it has the +`start-open' property; and goes after the extent if it has the +`end-open' property. Zero-length extents with both the `start-open' +and `end-open' properties are treated as if their starting point were +closed. Deletion of a character on a side of a zero-length extent +whose corresponding endpoint is closed causes the extent to be detached +if its `detachable' property is set; if the corresponding endpoint is +open, the extent remains in the buffer, moving as necessary. + + Extents are ordered within a buffer or string by increasing start +position, and then by decreasing end position (this is called the +"display order"). + + - Function: extent-start-position extent + This function returns the start position of EXTENT. + + - Function: extent-end-position extent + This function returns the end position of EXTENT. + + - Function: extent-length extent + This function returns the length of EXTENT in characters. If the + extent is detached, this returns `0'. If the extent is not + detached, this is equivalent to + (- (extent-end-position EXTENT) (extent-start-position EXTENT)) + + - Function: set-extent-endpoints extent start end &optional + buffer-or-string + This function sets the start and end position of EXTENT to START + and END. If both are `nil', this is equivalent to `detach-extent'. + + BUFFER-OR-STRING specifies the new buffer or string that the + extent should be in, and defaults to EXTENT's buffer or string. + (If `nil', and EXTENT is in no buffer and no string, it defaults + to the current buffer.) + + See documentation on `detach-extent' for a discussion of undo + recording. + + +File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents + +Finding Extents +=============== + +The following functions provide a simple way of determining the extents +in a buffer or string. A number of more sophisticated primitives for +mapping over the extents in a range of a buffer or string are also +provided (*note Mapping Over Extents::). When reading through this +section, keep in mind the way that extents are ordered (*note Extent +Endpoints::). + + - Function: extent-list &optional buffer-or-string from to flags + property value + This function returns a list of the extents in BUFFER-OR-STRING. + BUFFER-OR-STRING defaults to the current buffer if omitted. FROM + and TO can be used to limit the range over which extents are + returned; if omitted, all extents in the buffer or string are + returned. + + More specifically, if a range is specified using FROM and TO, only + extents that overlap the range (i.e. begin or end inside of the + range) are included in the list. FROM and TO default to the + beginning and end of BUFFER-OR-STRING, respectively. + + FLAGS controls how end cases are treated. For a discussion of + this, and exactly what "overlap" means, see `map-extents'. + + The optional arguments PROPERTY and VALUE can be used to further + restrict which extents are returned. They have the same meaning + as for `map-extents'. + + If you want to map a function over the extents in a buffer or + string, consider using `map-extents' or `mapcar-extents' instead. + + See also the function `extents-at'. + + Functions that create extents must be prepared for the possibility +that there are other extents in the same area, created by other +functions. To deal with this, functions typically mark their own +extents by setting a particular property on them. The following +function makes it easier to locate those extents. + + - Function: extent-at pos &optional object property before at-flag + This function finds the "smallest" extent (i.e., the last one in + the display order) at (i.e., overlapping) POS in OBJECT (a buffer + or string) having PROPERTY set. OBJECT defaults to the current + buffer. PROPERTY defaults to `nil', meaning that any extent will + do. Returns `nil' if there is no matching extent at POS. If the + fourth argument BEFORE is not `nil', it must be an extent; any + returned extent will precede that extent. This feature allows + `extent-at' to be used by a loop over extents. + + AT-FLAG controls how end cases are handled (i.e. what "at" really + means), and should be one of: + + `nil' + + `after' + An extent is at POS if it covers the character after POS. + This is consistent with the way that text properties work. + + `before' + An extent is at POS if it covers the character before POS. + + `at' + An extent is at POS if it overlaps or abuts POS. This + includes all zero-length extents at POS. + + Note that in all cases, the start-openness and end-openness of the + extents considered is ignored. If you want to pay attention to + those properties, you should use `map-extents', which gives you + more control. + + The following low-level functions are provided for explicitly +traversing the extents in a buffer according to the display order. +These functions are mostly intended for debugging--in normal operation, +you should probably use `mapcar-extents' or `map-extents', or loop +using the BEFORE argument to `extent-at', rather than creating a loop +using `next-extent'. + + - Function: next-extent extent + Given an extent EXTENT, this function returns the next extent in + the buffer or string's display order. If EXTENT is a buffer or + string, this returns the first extent in the buffer or string. + + - Function: previous-extent extent + Given an extent EXTENT, this function returns the previous extent + in the buffer or string's display order. If EXTENT is a buffer or + string, this returns the last extent in the buffer or string. + + +File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents + +Mapping Over Extents +==================== + +The most basic and general function for mapping over extents is called +`map-extents'. You should read through the definition of this function +to familiarize yourself with the concepts and optional arguments +involved. However, in practice you may find it more convenient to use +the function `mapcar-extents' or to create a loop using the `before' +argument to `extent-at' (*note Finding Extents::). + + - Function: map-extents function &optional object from to maparg flags + property value + This function maps FUNCTION over the extents which overlap a + region in OBJECT. OBJECT is normally a buffer or string but could + be an extent (see below). The region is normally bounded by + [FROM, TO) (i.e. the beginning of the region is closed and the end + of the region is open), but this can be changed with the FLAGS + argument (see below for a complete discussion). + + FUNCTION is called with the arguments (extent, MAPARG). The + arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and + default to the current buffer, the beginning of OBJECT, the end of + OBJECT, `nil', and `nil', respectively. `map-extents' returns the + first non-`nil' result produced by FUNCTION, and no more calls to + FUNCTION are made after it returns non-`nil'. + + If OBJECT is an extent, FROM and TO default to the extent's + endpoints, and the mapping omits that extent and its predecessors. + This feature supports restarting a loop based on `map-extents'. + Note: OBJECT must be attached to a buffer or string, and the + mapping is done over that buffer or string. + + An extent overlaps the region if there is any point in the extent + that is also in the region. (For the purpose of overlap, + zero-length extents and regions are treated as closed on both ends + regardless of their endpoints' specified open/closedness.) Note + that the endpoints of an extent or region are considered to be in + that extent or region if and only if the corresponding end is + closed. For example, the extent [5,7] overlaps the region [2,5] + because 5 is in both the extent and the region. However, (5,7] + does not overlap [2,5] because 5 is not in the extent, and neither + [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the + region. + + The optional FLAGS can be a symbol or a list of one or more + symbols, modifying the behavior of `map-extents'. Allowed symbols + are: + + `end-closed' + The region's end is closed. + + `start-open' + The region's start is open. + + `all-extents-closed' + Treat all extents as closed on both ends for the purpose of + determining whether they overlap the region, irrespective of + their actual open- or closedness. + + `all-extents-open' + Treat all extents as open on both ends. + + `all-extents-closed-open' + Treat all extents as start-closed, end-open. + + `all-extents-open-closed' + Treat all extents as start-open, end-closed. + + `start-in-region' + In addition to the above conditions for extent overlap, the + extent's start position must lie within the specified region. + Note that, for this condition, open start positions are + treated as if 0.5 was added to the endpoint's value, and open + end positions are treated as if 0.5 was subtracted from the + endpoint's value. + + `end-in-region' + The extent's end position must lie within the region. + + `start-and-end-in-region' + Both the extent's start and end positions must lie within the + region. + + `start-or-end-in-region' + Either the extent's start or end position must lie within the + region. + + `negate-in-region' + The condition specified by a `*-in-region' flag must _not_ + hold for the extent to be considered. + + At most one of `all-extents-closed', `all-extents-open', + `all-extents-closed-open', and `all-extents-open-closed' may be + specified. + + At most one of `start-in-region', `end-in-region', + `start-and-end-in-region', and `start-or-end-in-region' may be + specified. + + If optional arg PROPERTY is non-`nil', only extents with that + property set on them will be visited. If optional arg VALUE is + non-`nil', only extents whose value for that property is `eq' to + VALUE will be visited. + + If you want to map over extents and accumulate a list of results, +the following function may be more convenient than `map-extents'. + + - Function: mapcar-extents function &optional predicate + buffer-or-string from to flags property value + This function applies FUNCTION to all extents which overlap a + region in BUFFER-OR-STRING. The region is delimited by FROM and + TO. FUNCTION is called with one argument, the extent. A list of + the values returned by FUNCTION is returned. An optional + PREDICATE may be used to further limit the extents over which + FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and + VALUE may also be used to control the extents passed to PREDICATE + or FUNCTION, and have the same meaning as in `map-extents'. + + - Function: map-extent-children function &optional object from to + maparg flags property value + This function is similar to `map-extents', but differs in that: + + * It only visits extents which start in the given region. + + * After visiting an extent E, it skips all other extents which + start inside E but end before E's end. + + Thus, this function may be used to walk a tree of extents in a + buffer: + (defun walk-extents (buffer &optional ignore) + (map-extent-children 'walk-extents buffer)) + + - Function: extent-in-region-p extent &optional from to flags + This function returns `t' if `map-extents' would visit EXTENT if + called with the given arguments. + + +File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents + +Properties of Extents +===================== + +Each extent has a property list associating property names with values. +Some property names have predefined meanings, and can usually only +assume particular values. Assigning other values to such a property +either cause the value to be converted into a legal value (e.g., +assigning anything but `nil' to a Boolean property will cause the value +of `t' to be assigned to the property) or will cause an error. +Property names without predefined meanings can be assigned any value. +An undefined property is equivalent to a property with a value of +`nil', or with a particular default value in the case of properties +with predefined meanings. Note that, when an extent is created, the +`end-open' and `detachable' properties are set on it. + + If an extent has a parent, all of its properties actually derive +from that parent (or from the root ancestor if the parent in turn has a +parent), and setting a property of the extent actually sets that +property on the parent. *Note Extent Parents::. + + - Function: extent-property extent property &optional default + This function returns EXTENT's value for PROPERTY, or DEFAULT if + no such property exists. + + - Function: extent-properties extent + This function returns a list of all of EXTENT's properties that do + not have the value of `nil' (or the default value, for properties + with predefined meanings). + + - Function: set-extent-property extent property value + This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a + predefined meaning, only certain values are allowed, and some + values may be converted to others before being stored.) + + - Function: set-extent-properties extent plist + Change some properties of EXTENT. PLIST is a property list. This + is useful to change many extent properties at once. + + The following table lists the properties with predefined meanings, +along with their allowable values. + +`detached' + (Boolean) Whether the extent is detached. Setting this is the + same as calling `detach-extent'. *Note Detached Extents::. + +`destroyed' + (Boolean) Whether the extent has been deleted. Setting this is + the same as calling `delete-extent'. + +`priority' + (integer) The extent's redisplay priority. Defaults to 0. *Note + priority: Intro to Extents. This property can also be set with + `set-extent-priority' and accessed with `extent-priority'. + +`start-open' + (Boolean) Whether the start position of the extent is open, + meaning that characters inserted at that position go outside of + the extent. *Note Extent Endpoints::. + +`start-closed' + (Boolean) Same as `start-open' but with the opposite sense. + Setting this property clears `start-open' and vice-versa. + +`end-open' + (Boolean) Whether the end position of the extent is open, meaning + that characters inserted at that position go outside of the + extent. This is `t' by default. *Note Extent Endpoints::. + +`end-closed' + (Boolean) Same as `end-open' but with the opposite sense. Setting + this property clears `end-open' and vice-versa. + +`read-only' + (Boolean) Whether text within this extent will be unmodifiable. + +`face' + (face, face name, list of faces or face names, or `nil') The face + in which to display the extent's text. This property can also be + set with `set-extent-face' and accessed with `extent-face'. Note + that if a list of faces is specified, the faces are merged + together, with faces earlier in the list having priority over + faces later in the list. + +`mouse-face' + (face, face name, list of faces or face names, or `nil') The face + used to display the extent when the mouse moves over it. This + property can also be set with `set-extent-mouse-face' and accessed + with `extent-mouse-face'. Note that if a list of faces is + specified, the faces are merged together, with faces earlier in + the list having priority over faces later in the list. *Note + Extents and Events::. + +`pointer' + (pointer glyph) The glyph used as the pointer when the mouse + moves over the extent. This takes precedence over the + `text-pointer-glyph' and `nontext-pointer-glyph' variables. If + for any reason this glyph is an invalid pointer, the standard + glyphs will be used as fallbacks. *Note Mouse Pointer::. + +`detachable' + (Boolean) Whether this extent becomes detached when all of the + text it covers is deleted. This is `t' by default. *Note + Detached Extents::. + +`duplicable' + (Boolean) Whether this extent should be copied into strings, so + that kill, yank, and undo commands will restore or copy it. *Note + Duplicable Extents::. + +`unique' + (Boolean) Meaningful only in conjunction with `duplicable'. When + this is set, there may be only one instance of this extent + attached at a time. *Note Duplicable Extents::. + +`invisible' + (Boolean) If `t', text under this extent will not be displayed - + it will look as if the text and the begin-glyph is not there at + all. The end-glyph will still be displayed. + +`keymap' + (keymap or `nil') This keymap is consulted for mouse clicks on this + extent or keypresses made while `point' is within the extent. + *Note Extents and Events::. + +`copy-function' + This is a hook that is run when a duplicable extent is about to be + copied from a buffer to a string (or the kill ring). *Note + Duplicable Extents::. + +`paste-function' + This is a hook that is run when a duplicable extent is about to be + copied from a string (or the kill ring) into a buffer. *Note + Duplicable Extents::. + +`begin-glyph' + (glyph or `nil') This extent's begin glyph. *Note Annotations::. + +`end-glyph' + (glyph or `nil') This extent's end glyph. *Note Annotations::. + +`begin-glyph-layout' + (`text', `whitespace', `inside-margin', or `outside-margin') The + layout policy for this extent's begin glyph. Defaults to `text'. + *Note Annotations::. + +`end-glyph-layout' + (`text', `whitespace', `inside-margin', or `outside-margin') The + layout policy for this extent's end glyph. Defaults to `text'. + *Note Annotations::. + +`initial-redisplay-function' + (any funcallable object) The function to be called the first time + (a part of) the extent is redisplayed. It will be called with the + extent as its argument. + + This is used by `lazy-shot' to implement lazy font-locking. The + functionality is still experimental, and may change without further + notice. + + The following convenience functions are provided for accessing +particular properties of an extent. + + - Function: extent-face extent + This function returns the `face' property of EXTENT. This might + also return a list of face names. Do not modify this list + directly! Instead, use `set-extent-face'. + + Note that you can use `eq' to compare lists of faces as returned + by `extent-face'. In other words, if you set the face of two + different extents to two lists that are `equal' but not `eq', then + the return value of `extent-face' on the two extents will return + the identical list. + + - Function: extent-mouse-face extent + This function returns the `mouse-face' property of EXTENT. This + might also return a list of face names. Do not modify this list + directly! Instead, use `set-extent-mouse-face'. + + Note that you can use `eq' to compare lists of faces as returned + by `extent-mouse-face', just like for `extent-face'. + + - Function: extent-priority extent + This function returns the `priority' property of EXTENT. + + - Function: extent-keymap extent + This function returns the `keymap' property of EXTENT. + + - Function: extent-begin-glyph-layout extent + This function returns the `begin-glyph-layout' property of EXTENT, + i.e. the layout policy associated with the EXTENT's begin glyph. + + - Function: extent-end-glyph-layout extent + This function returns the `end-glyph-layout' property of EXTENT, + i.e. the layout policy associated with the EXTENT's end glyph. + + - Function: extent-begin-glyph extent + This function returns the `begin-glyph' property of EXTENT, i.e. + the glyph object displayed at the beginning of EXTENT. If there + is none, `nil' is returned. + + - Function: extent-end-glyph extent + This function returns the `end-glyph' property of EXTENT, i.e. the + glyph object displayed at the end of EXTENT. If there is none, + `nil' is returned. + + The following convenience functions are provided for setting +particular properties of an extent. + + - Function: set-extent-priority extent priority + This function sets the `priority' property of EXTENT to PRIORITY. + + - Function: set-extent-face extent face + This function sets the `face' property of EXTENT to FACE. + + - Function: set-extent-mouse-face extent face + This function sets the `mouse-face' property of EXTENT to FACE. + + - Function: set-extent-keymap extent keymap + This function sets the `keymap' property of EXTENT to KEYMAP. + KEYMAP must be either a keymap object, or `nil'. + + - Function: set-extent-begin-glyph-layout extent layout + This function sets the `begin-glyph-layout' property of EXTENT to + LAYOUT. + + - Function: set-extent-end-glyph-layout extent layout + This function sets the `end-glyph-layout' property of EXTENT to + LAYOUT. + + - Function: set-extent-begin-glyph extent begin-glyph &optional layout + This function sets the `begin-glyph' and `glyph-layout' properties + of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT + defaults to `text' if not specified.) + + - Function: set-extent-end-glyph extent end-glyph &optional layout + This function sets the `end-glyph' and `glyph-layout' properties + of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults + to `text' if not specified.) + + - Function: set-extent-initial-redisplay-function extent function + This function sets the `initial-redisplay-function' property of the + extent to FUNCTION. + + +File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents + +Detached Extents +================ + +A detached extent is an extent that is not attached to a buffer or +string but can be re-inserted. Detached extents have a start position +and end position of `nil'. Extents can be explicitly detached using +`detach-extent'. An extent is also detached when all of its characters +are all killed by a deletion, if its `detachable' property is set; if +this property is not set, the extent becomes a zero-length extent. +(Zero-length extents with the `detachable' property set behave +specially. *Note zero-length extents: Extent Endpoints.) + + - Function: detach-extent extent + This function detaches EXTENT from its buffer or string. If + EXTENT has the `duplicable' property, its detachment is tracked by + the undo mechanism. *Note Duplicable Extents::. + + - Function: extent-detached-p extent + This function returns `nil' if EXTENT is detached, and `t' + otherwise. + + - Function: copy-extent extent &optional object + This function makes a copy of EXTENT. It is initially detached. + Optional argument OBJECT defaults to EXTENT's object (normally a + buffer or string, but could be `nil'). + + - Function: insert-extent extent &optional start end no-hooks object + This function inserts EXTENT from START to END in OBJECT (a buffer + or string). If EXTENT is detached from a different buffer or + string, or in most cases when EXTENT is already attached, the + extent will first be copied as if with `copy-extent'. This + function operates the same as if `insert' were called on a string + whose extent data calls for EXTENT to be inserted, except that if + NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be + invoked. *Note Duplicable Extents::. + + +File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents + +Extent Parents +============== + +An extent can have a parent extent set for it. If this is the case, +the extent derives all its properties from that extent and has no +properties of its own. The only "properties" that the extent keeps are +the buffer or string it refers to and the start and end points. (More +correctly, the extent's own properties are shadowed. If you later +change the extent to have no parent, its own properties will become +visible again.) + + It is possible for an extent's parent to itself have a parent, and +so on. Through this, a whole tree of extents can be created, all +deriving their properties from one root extent. Note, however, that +you cannot create an inheritance loop--this is explicitly disallowed. + + Parent extents are used to implement the extents over the modeline. + + - Function: set-extent-parent extent parent + This function sets the parent of EXTENT to PARENT. If PARENT is + `nil', the extent is set to have no parent. + + - Function: extent-parent extent + This function return the parents (if any) of EXTENT, or `nil'. + + - Function: extent-children extent + This function returns a list of the children (if any) of EXTENT. + The children of an extent are all those extents whose parent is + that extent. This function does not recursively trace children of + children. + + - Function: extent-descendants extent + This function returns a list of all descendants of EXTENT, + including EXTENT. This recursively applies `extent-children' to + any children of EXTENT, until no more children can be found. + + +File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents + +Duplicable Extents +================== + +If an extent has the `duplicable' property, it will be copied into +strings, so that kill, yank, and undo commands will restore or copy it. + + Specifically: + + * When a string is created using `buffer-substring' or + `buffer-string', any duplicable extents in the region corresponding + to the string will be copied into the string (*note Buffer + Contents::). When the string is inserted into a buffer using + `insert', `insert-before-markers', `insert-buffer' or + `insert-buffer-substring', the extents in the string will be copied + back into the buffer (*note Insertion::). The extents in a string + can, of course, be retrieved explicitly using the standard extent + primitives over the string. + + * Similarly, when text is copied or cut into the kill ring, any + duplicable extents will be remembered and reinserted later when + the text is pasted back into a buffer. + + * When `concat' is called on strings, the extents in the strings are + copied into the resulting string. + + * When `substring' is called on a string, the relevant extents are + copied into the resulting string. + + * When a duplicable extent is detached by `detach-extent' or string + deletion, or inserted by `insert-extent' or string insertion, the + action is recorded by the undo mechanism so that it can be undone + later. Note that if an extent gets detached and then a later undo + causes the extent to get reinserted, the new extent will not be + `eq' to the original extent. + + * Extent motion, face changes, and attachment via `make-extent' are + not recorded by the undo mechanism. This means that extent changes + which are to be undo-able must be performed by character editing, + or by insertion and detachment of duplicable extents. + + * A duplicable extent's `copy-function' property, if non-`nil', + should be a function, and will be run when a duplicable extent is + about to be copied from a buffer to a string (or the kill ring). + It is called with three arguments: the extent and the buffer + positions within it which are being copied. If this function + returns `nil', then the extent will not be copied; otherwise it + will. + + * A duplicable extent's `paste-function' property, if non-`nil', + should be a function, and will be run when a duplicable extent is + about to be copied from a string (or the kill ring) into a buffer. + It is called with three arguments: the original extent and the + buffer positions which the copied extent will occupy. (This hook + is run after the corresponding text has already been inserted into + the buffer.) Note that the extent argument may be detached when + this function is run. If this function returns `nil', no extent + will be inserted. Otherwise, there will be an extent covering the + range in question. + + Note: if the extent to be copied is already attached to the buffer + and overlaps the new range, the extent will simply be extended and + the `paste-function' will not be called. + + +File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents + +Interaction of Extents with Keyboard and Mouse Events +===================================================== + +If an extent has the `mouse-face' property set, it will be highlighted +when the mouse passes over it. This includes the begin-glyph, but not +the end-glyph. Highlighting is accomplished by merging the extent's +face with the face or faces specified by the `mouse-face' property. +The effect is as if a pseudo-extent with the `mouse-face' face were +inserted after the extent in the display order (*note Extent +Endpoints::, display order). + + - Variable: mouse-highlight-priority + This variable holds the priority to use when merging in the + highlighting pseudo-extent. The default is 1000. This is + purposely set very high so that the highlighting pseudo-extent + shows up even if there are other extents with various priorities + at the same location. + + You can also explicitly cause an extent to be highlighted. Only one +extent at a time can be highlighted in this fashion, and any other +highlighted extent will be de-highlighted. + + - Function: highlight-extent extent &optional highlight-p + This function highlights (if HIGHLIGHT-P is non-`nil') or + de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the + `mouse-face' property. (Nothing happens if EXTENT does not have + the `mouse-face' property.) + + - Function: force-highlight-extent extent &optional highlight-p + This function is similar to `highlight-extent' but highlights or + de-highlights the extent regardless of whether it has the + `mouse-face' property. + + If an extent has a `keymap' property, this keymap will be consulted +for mouse clicks on the extent and keypresses made while `point' is +within the extent. The behavior of mouse clicks and keystrokes not +defined in the keymap is as normal for the buffer. + + +File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents + +Atomic Extents +============== + +If the Lisp file `atomic-extents' is loaded, then the atomic extent +facility is available. An "atomic extent" is an extent for which +`point' cannot be positioned anywhere within it. This ensures that +when selecting text, either all or none of the extent is selected. + + To make an extent atomic, set its `atomic' property. + + +File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top + +Specifiers +********** + +A specifier is an object used to keep track of a property whose value +should vary according to _display context_, a window, a frame, or +device. The value of many built-in properties, such as the font, +foreground, background, and such properties of a face and variables +such as `modeline-shadow-thickness' and `top-toolbar-height', is +actually a specifier object. The specifier object, in turn, is +"instanced" in a particular situation to yield the real value of the +property in the current context. + + - Function: specifierp object + This function returns non-`nil' if OBJECT is a specifier. + +* Menu: + +* Introduction to Specifiers:: Specifiers provide a clean way for + display and other properties to vary + (under user control) in a wide variety + of contexts. +* Simple Specifier Usage:: Getting started with specifiers. +* Specifiers In-Depth:: Gory details about specifier innards. +* Specifier Instancing:: Instancing means obtaining the ``value'' of + a specifier in a particular context. +* Specifier Types:: Specifiers come in different flavors. +* Adding Specifications:: Specifications control a specifier's ``value'' + by giving conditions under which a + particular value is valid. +* Retrieving Specifications:: Querying a specifier's specifications. +* Specifier Tag Functions:: Working with specifier tags. +* Specifier Instancing Functions:: + Functions to instance a specifier. +* Specifier Examples:: Making all this stuff clearer. +* Creating Specifiers:: Creating specifiers for your own use. +* Specifier Validation Functions:: + Validating the components of a specifier. +* Other Specification Functions:: + Other ways of working with specifications. + + +File: lispref.info, Node: Introduction to Specifiers, Next: Simple Specifier Usage, Up: Specifiers + +Introduction to Specifiers +========================== + +Perhaps the most useful way to explain specifiers is via an analogy. +Emacs Lisp programmers are used to _buffer-local variables_ *Note +Buffer-Local Variables::. For example, the variable `modeline-format', +which controls the format of the modeline, can have different values +depending on the particular buffer being edited. The variable has a +default value which most modes will use, but a specialized package such +as Calendar might change the variable so as to tailor the modeline to +its own purposes. Other variables are perhaps best thought of as "mode +local," such as font-lock keywords, but they are implemented as buffer +locals. + + Other properties (such as those that can be changed by the +`modify-frame-parameters' function, for example the color of the text +cursor) can have frame-local values, although it might also make sense +for them to have buffer-local values. In other cases, you might want +the property to vary depending on the particular window within the +frame that applies (e.g. the top or bottom window in a split frame), the +device type that that frame appears on (X or tty), etc. Perhaps you can +envision some more complicated scenario where you want a particular +value in a specified buffer, another value in all other buffers +displayed on a particular frame, another value in all other buffers +displayed in all other frames on any mono (two-color, e.g. black and +white only) displays, and a default value in all other circumstances. + + Specifiers generalize both buffer- and frame-local properties. +Specifiers vary according to the _display_ context. Font-lock keywords +in a buffer will be the same no matter which window the buffer is +displayed in, but windows on TTY devices will simply not be capable of +the flexibility that windows on modern GUI devices are. Specifiers +provide a way for the programmer to _declare_ that an emphasized text +should be italic on GUI devices and inverse video on TTYs. They also +provide a way for the programmer to declare fallbacks, so that a color +specified as "chartreuse" where possible can fall back to "yellow" on +devices where only ANSI (4-bit) color is available. The complex +calculations and device querying are transparent to both user and +programmer. You ask for what you want; it's up to XEmacs to provide +it, or a reasonable approximation. + + We call such a declaration a "specification". A "specification" +applies in a particular "locale", which is a window, buffer, frame, +device, or the global locale. The value part of the specification is +called an "instantiator". The process of determining the value in a +particular context, or "domain", is called "instantiation" or +"instancing". A domain is a window, frame, or device. + + The difference between "locale" and "domain" is somewhat subtle. +You may think of a locale as a class of domains, which may span +different devices. Since the specification is abstract (a Lisp form), +you can state it without reference to a device. On the other hand, when +you instantiate a specification, you must know the type of the device. +It is useless to specify that "blue means emphasis" on a monochrome +device. Thus instantiation requires specification of the device on +which it will be rendered. + + Thus a "specifier" allows a great deal of flexibility in controlling +exactly what value a property has in which circumstances. Specifiers +are most commonly used for display properties, such as an image or the +foreground color of a face. As a simple example, you can specify that +the foreground of the default face be + + * blue for a particular buffer + + * green for all other buffers + + As a more complicated example, you could specify that the foreground +of the default face be + + * forest green for all buffers displayed in a particular Emacs + window, or green if the X server doesn't recognize the color + `forest green' + + * blue for all buffers displayed in a particular frame + + * red for all other buffers displayed on a color device + + * white for all other buffers + + +File: lispref.info, Node: Simple Specifier Usage, Next: Specifiers In-Depth, Prev: Introduction to Specifiers, Up: Specifiers + +Simple Specifier Usage +====================== + +A useful specifier application is adding a button to a toolbar. XEmacs +provides several toolbars, one along each edge of the frame. Normally +only one is used at a time, the default. The default toolbar is +actually a specifier object which is the value of `default-toolbar'. +*Note Toolbar Intro::. + + The specification of a toolbar is simple: it is a list of buttons. +Each button is a vector with four elements: an icon, a command, the +enabled flag, and a help string. Let's retrieve the instance of the +toolbar you see in the selected frame. + + (specifier-instance default-toolbar) + + The value returned is, as promised, a list of vectors. Now let's +build up a button, and add it to the toolbar. Our button will invoke +the last defined keyboard macro. This is an alternative to +`name-last-kbd-macro' for creating a persistent macro, rather than an +alias for `C-x e'. + + A toolbar button icon can be quite sophisticated, with different +images for button up, button down, and disabled states, and a similar +set with captions. We'll use a very simple icon, but we have to jump +through a few non-obvious hoops designed to support the sophisticated +applications. The rest of the button descriptor is straightforward. + + (setq toolbar-my-kbd-macro-button + `[ (list (make-glyph "MyKbdMac")) + (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) + t + "Execute a previously defined keyboard macro." ]) + + (set-specifier default-toolbar + (cons toolbar-my-kbd-macro-button + (specifier-specs default-toolbar 'global)) + 'global) + + To remove the button, just substitute the function `delete' for the +`cons' above. + + What is the difference between `specifier-instance', which we used +in the example of retrieving the toolbar descriptor, and +`specifier-specs', which was used in the toolbar manipulating code? +`specifier-specs' retrieves a copy of the instantiator, which is +abstract and does not depend on context. `specifier-instance', on the +other hand, actually instantiates the specification, and returns the +result for the given context. Another way to express this is: +`specifier-specs' takes a _locale_ as an argument, while +`specifier-instance' takes a _domain_. The reason for providing +`specifier-instance' is that sometimes you wish to see the object that +XEmacs will actually use. `specifier-specs', on the other hand, shows +you what the programmer (or user) requested. When a program +manipulates specifications, clearly it's the latter that is desirable. + + In the case of the toolbar descriptor, it turns out that these are +the same: the instancing process is trivial. However, many +specifications have non-trivial instancing. Compare the results of the +following forms on my system. (The `(cdr (first ...))' form is due to +my use of Mule. On non-Mule XEmacsen, just use `specifier-specs'.) + + (cdr (first (specifier-specs (face-font 'default) 'global))) + => "-*--14-*jisx0208*-0" + + (specifier-instance (face-font 'default)) + # 0xe0028b 0x176b> + + In this case, `specifier-instance' returns an opaque object; +programs can't work on it, they can only pass it around. Worse, in some +environments the instantiation will fail, resulting in a different value +(when another instantiation succeeds), or worse yet, an error, if all +attempts to instance the specifier fail. `specifier-instance' is +context-dependent, even for the exact same specification. +`specifier-specs' is deterministic, and only depends on the +specifications. + + Note that in the toolbar-changing code we operate in the global +locale. This means that narrower locales, if they have specifications, +will shadow our changes. (Specifier instancing does not merge +specifications. It selects the "highest-priority successful +specification" and instances that.) + + In fact, in our example, it seems pretty likely that different +buffers _should_ have different buttons. (The icon can be the same, but +the keyboard macro you create in a Dired buffer is highly unlikely to be +useful in a LaTeX buffer!) Here's one way to implement this: + + (setq toolbar-my-kbd-macro-button + `[ (list (make-glyph "MyKbdMac")) + (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) + t + "Execute a previously defined keyboard macro." ]) + + (set-specifier default-toolbar + (cons toolbar-my-kbd-macro-button + (cond ((specifier-specs default-toolbar + (current-buffer))) + ((specifier-specs default-toolbar + 'global))) + (current-buffer)) + + Finally, a cautionary note: the use of `specifier-specs' in the code +above is for expository purposes. Don't use it in production code. In +fact, the `set-specifier' form above is likely to fail occasionally, +because you can add many specifications for the same locale. + + In these cases, `specifier-specs' will return a list. A further +refinement is that a specification may be associated with a set of +"specifier tags". If the list of specifier tags is non-nil, then +`specifier-specs' will return a cons of the tag set and the +instantiator. Evidently `specifier-specs' is a bit unreliable. (For +toolbars, the code above should work 99% of the time, because toolbars +are rarely changed. Since instantiation is trivial, multiple specs are +not useful--the first one always succeeds.) + + In fact, `specifier-specs' is intended to be used to display specs +to humans with a minimum of clutter. The robust way to access +specifications is via `specifier-spec-list'. *Note Adding +Specifications::, for the definition of "spec-list". *Note Retrieving +Specifications::, for documentation of `specifier-specs' and +`specifier-spec-list'. To get the desired effect, replace the form +`(specifier-spec default-toolbar 'global)' with + + (cdr (second (first (specifier-spec-list default-toolbar 'global)))) + + (It should be obvious why the example uses the lazy unreliable +method!) + + +File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Simple Specifier Usage, Up: Specifiers + +In-Depth Overview of a Specifier +================================ + +Having variables vary according the editing context is very useful, and +the buffer is the natural "atomic" unit of editing context. In a GUI +environment, it can be similarly useful to have variables whose values +vary according to display context. The atomic unit of display context +is the Emacs window. Buffers are cleanly grouped by modes, but windows +are not so easily pigeonholed. On the one hand, a window displays a +buffer, and thus one possible hierarchy is window, buffer, mode. On the +other, a window is a component of a frame. This generates the window, +frame, device hierarchy. Finally, there are objects such as toolbars +whose properties are described by specifiers. These do not fit +naturally into either hierarchy. This problem is as yet not cleanly +solved. + + Another potential source of conceptual confusion is the instantiation +process. Instantiating a buffer-local variable is simple: at any given +point in time there is a current buffer, and its local values are used +and set whenever the variable is accessed, unless the programmer goes to +some special effort (uses `default-value' and `set-default'. However, +a specifier object encapsulates a set of "specifications", each of +which says what its value should be if a particular condition applies. +Several such conditions might apply simultaneously in a given window. + + For example, one specification might be "The value should be +darkseagreen2 on X devices" another might be "The value should be blue +in the *Help* buffer". So what do we do for "the *Help* buffer on an X +device"? The answer is simple: give each type of locale a priority and +check them in priority order, returning the first instantiator that +successfully instantiates a value. + + Given a specifier, a logical question is "What is its value in a +particular situation?" This involves looking through the specifications +to see which ones apply to this particular situation, and perhaps +preferring one over another if more than one applies. In specifier +terminology, a "particular situation" is called a "domain", and +determining its value in a particular domain is called "instancing". +Most of the time, a domain is identified by a particular window. For +example, if the redisplay engine is drawing text in the default face in +a particular window, it retrieves the specifier for the foreground color +of the default face and "instances" it in the domain given by that +window; in other words, it asks the specifier, "What is your value in +this window?". + + Note that the redisplay example is in a sense canonical. That is, +specifiers are designed to present a uniform and _efficient_ API to +redisplay. It is the efficiency constraint that motivates the +introduction of specifier tags, and many restrictions on access (for +example, a buffer is not a domain, and you cannot instantiate a +specifier over a buffer). + + More specifically, a specifier contains a set of "specifications", +each of which associates a "locale" (a window object, a buffer object, +a frame object, a device object, or the symbol `global') with an +"inst-list", which is a list of one or more "inst-pairs". (For each +possible locale, there can be at most one specification containing that +locale.) Each inst-pair is a cons of a "tag set" (an unordered list of +zero or more symbols, or "tags") and an "instantiator" (the allowed +form of this varies depending on the type of specifier). In a given +specification, there may be more than one inst-pair with the same tag +set; this is unlike for locales. + + The tag set is used to restrict the sorts of devices over which the +instantiator is valid and to uniquely identify instantiators added by a +particular application, so that different applications can work on the +same specifier and not interfere with each other. Each tag can have a +"predicate" associated with it, which is a function of one argument (a +device) that specifies whether the tag matches that particular device. +(If a tag does not have a predicate, it matches all devices.) All tags +in a tag set must match a device for the associated inst-pair to be +instantiable over that device. (A null tag set is perfectly valid, and +trivially matches all devices.) + + The valid device types (normally `x', `tty', and `stream') and +device classes (normally `color', `grayscale', and `mono') can always +be used as tags, and match devices of the associated type or class +(*note Consoles and Devices::). User-defined tags may be defined, with +an optional predicate specified. An application can create its own +tag, use it to mark all its instantiators, and be fairly confident that +it will not interfere with other applications that modify the same +specifier--Functions that add a specification to a specifier usually +only overwrite existing inst-pairs with the same tag set as was given, +and a particular tag or tag set can be specified when removing +instantiators. + + When a specifier is instanced in a domain, both the locale and the +tag set can be viewed as specifying necessary conditions that must +apply in that domain for an instantiator to be considered as a possible +result of the instancing. More specific locales always override more +general locales (thus, there is no particular ordering of the +specifications in a specifier); however, the tag sets are simply +considered in the order that the inst-pairs occur in the +specification's inst-list. + + Note also that the actual object that results from the instancing +(called an "instance object") may not be the same as the instantiator +from which it was derived. For some specifier types (such as integer +specifiers and boolean specifiers), the instantiator will be returned +directly as the instance object. For other types, however, this is not +the case. For example, for font specifiers, the instantiator is a +font-description string and the instance object is a font-instance +object, which describes how the font is displayed on a particular +device. A font-instance object encapsulates such things as the actual +font name used to display the font on that device (a font-description +string under X is usually a wildcard specification that may resolve to +different font names, with possibly different foundries, widths, etc., +on different devices), the extra properties of that font on that +device, etc. Furthermore, this conversion (called "instantiation") +might fail--a font or color might not exist on a particular device, for +example. + + +File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers + +How a Specifier Is Instanced +============================ + +Instancing of a specifier in a particular window domain proceeds as +follows: + + * First, XEmacs searches for a specification whose locale is the + same as the window. If that fails, the search is repeated, + looking for a locale that is the same as the window's buffer. If + that fails, the search is repeated using the window's frame, then + using the device that frame is on. Finally, the specification + whose locale is the symbol `global' (if there is such a + specification) is considered. + + * The inst-pairs contained in the specification that was found are + considered in their order in the inst-list, looking for one whose + tag set matches the device that is derived from the window domain. + (The tag set is an unordered list of zero or more tag symbols. + For all tags that have predicates associated with them, the + predicate must match the device.) + + * If a matching tag set is found, the corresponding instantiator is + passed to the specifier's instantiation method, which is specific + to the type of the specifier. If it succeeds, the resulting + instance object is returned as the result of the instancing and + the instancing is done. Otherwise, the operation continues, + looking for another matching inst-pair in the current + specification. + + * When there are no more inst-pairs to be considered in the current + specification, the search starts over, looking for another + specification as in the first step above. + + * If all specifications are exhausted and no instance object can be + derived, the instancing fails. (Actually, this is not completely + true. Some specifier objects for built-in properties have a + "fallback" value, which is either an inst-list or another + specifier object, that is consulted if the instancing is about to + fail. If it is an inst-list, the searching proceeds using the + inst-pairs in that list. If it is a specifier, the entire + instancing starts over using that specifier instead of the given + one. Fallback values are set by the C code and cannot be + modified, except perhaps indirectly, using any Lisp functions. + The purpose of them is to supply some values to make sure that + instancing of built-in properties can't fail and to implement some + basic specifier inheritance, such as the fact that faces inherit + their properties from the `default' face.) + + It is also possible to instance a specifier over a frame domain or +device domain instead of over a window domain. The C code, for example, +instances the `top-toolbar-height' variable over a frame domain in +order to determine the height of a frame's top toolbar. Instancing over +a frame or device is similar to instancing over a window except that +specifications for locales that cannot be derived from the domain are +ignored. Specifically, instancing over a frame looks first for frame +locales, then device locales, then the `global' locale. Instancing +over a device domain looks only for device locales and the `global' +locale. + + +File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers + +Specifier Types +=============== + +There are various different types of specifiers. The type of a +specifier controls what sorts of instantiators are valid, how an +instantiator is instantiated, etc. Here is a list of built-in specifier +types: + +`boolean' + The valid instantiators are the symbols `t' and `nil'. Instance + objects are the same as instantiators so no special instantiation + function is needed. + +`integer' + The valid instantiators are integers. Instance objects are the + same as instantiators so no special instantiation function is + needed. `modeline-shadow-thickness' is an example of an integer + specifier (negative thicknesses indicate that the shadow is drawn + recessed instead of raised). + +`natnum' + The valid instantiators are natnums (non-negative integers). + Instance objects are the same as instantiators so no special + instantiation function is needed. Natnum specifiers are used for + dimension variables such as `top-toolbar-height'. + +`generic' + All Lisp objects are valid instantiators. Instance objects are + the same as instantiators so no special instantiation function is + needed. + +`font' + The valid instantiators are strings describing fonts or vectors + indicating inheritance from the font of some face. Instance + objects are font-instance objects, which are specific to a + particular device. The instantiation method for font specifiers + can fail, unlike for integer, natnum, boolean, and generic + specifiers. + +`color' + The valid instantiators are strings describing colors or vectors + indicating inheritance from the foreground or background of some + face. Instance objects are color-instance objects, which are + specific to a particular device. The instantiation method for + color specifiers can fail, as for font specifiers. + +`image' + Images are perhaps the most complicated type of built-in + specifier. The valid instantiators are strings (a filename, + inline data for a pixmap, or text to be displayed in a text glyph) + or vectors describing inline data of various sorts or indicating + inheritance from the background-pixmap property of some face. + Instance objects are either strings (for text images), + image-instance objects (for pixmap images), or subwindow objects + (for subwindow images). The instantiation method for image + specifiers can fail, as for font and color specifiers. + +`face-boolean' + The valid instantiators are the symbols `t' and `nil' and vectors + indicating inheritance from a boolean property of some face. + Specifiers of this sort are used for all of the built-in boolean + properties of faces. Instance objects are either the symbol `t' + or the symbol `nil'. + +`toolbar' + The valid instantiators are toolbar descriptors, which are lists + of toolbar-button descriptors (each of which is a vector of two or + four elements). *Note Toolbar::, for more information. + + Color and font instance objects can also be used in turn as +instantiators for a new color or font instance object. Since these +instance objects are device-specific, the instantiator can be used +directly as the new instance object, but only if they are of the same +device. If the devices differ, the base color or font of the +instantiating object is effectively used instead as the instantiator. + + *Note Faces and Window-System Objects::, for more information on +fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more +information about image specifiers. *Note Toolbar::, for more +information on toolbar specifiers. + + - Function: specifier-type specifier + This function returns the type of SPECIFIER. The returned value + will be a symbol: one of `integer', `boolean', etc., as listed in + the above table. + + Functions are also provided to query whether an object is a +particular kind of specifier: + + - Function: boolean-specifier-p object + This function returns non-`nil' if OBJECT is a boolean specifier. + + - Function: integer-specifier-p object + This function returns non-`nil' if OBJECT is an integer specifier. + + - Function: natnum-specifier-p object + This function returns non-`nil' if OBJECT is a natnum specifier. + + - Function: generic-specifier-p object + This function returns non-`nil' if OBJECT is a generic specifier. + + - Function: face-boolean-specifier-p object + This function returns non-`nil' if OBJECT is a face-boolean + specifier. + + - Function: toolbar-specifier-p object + This function returns non-`nil' if OBJECT is a toolbar specifier. + + - Function: font-specifier-p object + This function returns non-`nil' if OBJECT is a font specifier. + + - Function: color-specifier-p object + This function returns non-`nil' if OBJECT is a color specifier. + + - Function: image-specifier-p object + This function returns non-`nil' if OBJECT is an image specifier. + + +File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers + +Adding specifications to a Specifier +==================================== + + - Function: add-spec-to-specifier specifier instantiator &optional + locale tag-set how-to-add + This function adds a specification to SPECIFIER. The + specification maps from LOCALE (which should be a window, buffer, + frame, device, or the symbol `global', and defaults to `global') + to INSTANTIATOR, whose allowed values depend on the type of the + specifier. Optional argument TAG-SET limits the instantiator to + apply only to the specified tag set, which should be a list of + tags all of which must match the device being instantiated over + (tags are a device type, a device class, or tags defined with + `define-specifier-tag'). Specifying a single symbol for TAG-SET + is equivalent to specifying a one-element list containing that + symbol. Optional argument HOW-TO-ADD specifies what to do if + there are already specifications in the specifier. It should be + one of + + `prepend' + Put at the beginning of the current list of instantiators for + LOCALE. + + `append' + Add to the end of the current list of instantiators for + LOCALE. + + `remove-tag-set-prepend' + This is the default. Remove any existing instantiators whose + tag set is the same as TAG-SET; then put the new instantiator + at the beginning of the current list. + + `remove-tag-set-append' + Remove any existing instantiators whose tag set is the same as + TAG-SET; then put the new instantiator at the end of the + current list. + + `remove-locale' + Remove all previous instantiators for this locale before + adding the new spec. + + `remove-locale-type' + Remove all specifications for all locales of the same type as + LOCALE (this includes LOCALE itself) before adding the new + spec. + + `remove-all' + Remove all specifications from the specifier before adding + the new spec. + + `remove-tag-set-prepend' is the default. + + You can retrieve the specifications for a particular locale or + locale type with the function `specifier-spec-list' or + `specifier-specs'. + + - Function: add-spec-list-to-specifier specifier spec-list &optional + how-to-add + This function adds a "spec-list" (a list of specifications) to + SPECIFIER. The format of a spec-list is + + `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' + + where + + * LOCALE := a window, a buffer, a frame, a device, or `global' + + * TAG-SET := an unordered list of zero or more TAGS, each of + which is a symbol + + * TAG := a device class (*note Consoles and Devices::), a + device type, or a tag defined with `define-specifier-tag' + + * INSTANTIATOR := format determined by the type of specifier + + The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A + list of inst-pairs is called an "inst-list". The pair `(LOCALE . + INST-LIST)' is called a "specification". A spec-list, then, can + be viewed as a list of specifications. + + HOW-TO-ADD specifies how to combine the new specifications with + the existing ones, and has the same semantics as for + `add-spec-to-specifier'. + + The higher-level function `set-specifier' is often more convenient + because it allows abbreviations of spec-lists to be used instead + of the heavily nested canonical syntax. However, one should take + great care in using them with specifiers types which can have lists + as instantiators, such as toolbar specifiers and generic + specifiers. In those cases it's probably best to use + `add-spec-to-specifier' or `add-spec-list-to-specifier'. + + - Special Form: let-specifier specifier-list &rest body + This special form temporarily adds specifications to specifiers, + evaluates forms in BODY and restores the specifiers to their + previous states. The specifiers and their temporary + specifications are listed in SPECIFIER-LIST. + + The format of SPECIFIER-LIST is + + ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) + + SPECIFIER is the specifier to be temporarily modified. VALUE is + the instantiator to be temporarily added to specifier in LOCALE. + LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in + `add-spec-to-specifier'. + + This special form is implemented as a macro; the code resulting + from macro expansion will add specifications to specifiers using + `add-spec-to-specifier'. After forms in BODY are evaluated, the + temporary specifications are removed and old specifier spec-lists + are restored. + + LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to + `nil'. The value of the last form in BODY is returned. + + NOTE: If you want the specifier's instance to change in all + circumstances, use `(selected-window)' as the LOCALE. If LOCALE + is `nil' or omitted, it defaults to `global'. + + The following example removes the 3D modeline effect in the + currently selected window for the duration of a second: + + (let-specifier ((modeline-shadow-thickness 0 (selected-window))) + (sit-for 1)) + + - Function: set-specifier specifier value &optional locale tag-set + how-to-add + This function adds some specifications to SPECIFIER. VALUE can be + a single instantiator or tagged instantiator (added as a global + specification), a list of tagged and/or untagged instantiators + (added as a global specification), a cons of a locale and + instantiator or locale and instantiator list, a list of such + conses, or nearly any other reasonable form. More specifically, + VALUE can be anything accepted by `canonicalize-spec-list' + (described below). + + LOCALE, TAG-SET, and HOW-TO-ADD are the same as in + `add-spec-to-specifier'. + + Note that `set-specifier' is exactly complementary to + `specifier-specs' except in the case where SPECIFIER has no specs + at all in it but `nil' is a valid instantiator (in that case, + `specifier-specs' will return `nil' (meaning no specs) and + `set-specifier' will interpret the `nil' as meaning "I'm adding a + global instantiator and its value is `nil'"), or in strange cases + where there is an ambiguity between a spec-list and an inst-list, + etc. (The built-in specifier types are designed in such a way as + to avoid any such ambiguities.) For robust code, `set-specifier' + should probably be avoided for specifier types which accept lists + as instantiators (currently toolbar specifiers and generic + specifiers). + + If you want to work with spec-lists, you should probably not use + these functions, but should use the lower-level functions + `specifier-spec-list' and `add-spec-list-to-specifier'. These + functions always work with fully-qualified spec-lists; thus, there + is no ambiguity. + + - Function: canonicalize-inst-pair inst-pair specifier-type &optional + noerror + This function canonicalizes the given INST-PAIR. + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + Canonicalizing means converting to the full form for an inst-pair, + i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator + is given a tag set of `nil' (the empty set), and a single tag is + converted into a tag set consisting only of that tag. + + If NOERROR is non-`nil', signal an error if the inst-pair is + invalid; otherwise return `t'. + + - Function: canonicalize-inst-list inst-list specifier-type &optional + noerror + This function canonicalizes the given INST-LIST (a list of + inst-pairs). + + SPECIFIER-TYPE specifies the type of specifier that this INST-LIST + will be used for. + + Canonicalizing means converting to the full form for an inst-list, + i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a + single inst-pair or any abbreviation thereof or a list of + (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) + + If NOERROR is non-`nil', signal an error if the inst-list is + invalid; otherwise return `t'. + + - Function: canonicalize-spec spec specifier-type &optional noerror + This function canonicalizes the given SPEC (a specification). + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + Canonicalizing means converting to the full form for a spec, i.e. + `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a + possibly abbreviated inst-list or a cons of a locale and a + possibly abbreviated inst-list. (See `canonicalize-inst-list'.) + + If NOERROR is `nil', signal an error if the specification is + invalid; otherwise return `t'. + + - Function: canonicalize-spec-list spec-list specifier-type &optional + noerror + This function canonicalizes the given SPEC-LIST (a list of + specifications). + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + If NOERROR is `nil', signal an error if the spec-list is invalid; + otherwise return `t' for an invalid spec-list. (Note that this + cannot be confused with a canonical spec-list.) + + Canonicalizing means converting to the full form for a spec-list, + i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This + function accepts a possibly abbreviated specification or a list of + such things. (See `canonicalize-spec'.) This is the function used + to convert spec-lists accepted by `set-specifier' and such into a + form suitable for `add-spec-list-to-specifier'. + + This function tries extremely hard to resolve any ambiguities, and + the built-in specifier types (font, image, toolbar, etc.) are + designed so that there won't be any ambiguities. + + The canonicalization algorithm is as follows: + + 1. Attempt to parse SPEC-LIST as a single, possibly abbreviated, + specification. + + 2. If that fails, attempt to parse SPEC-LIST as a list of + (abbreviated) specifications. + + 3. If that fails, SPEC-LIST is invalid. + + A possibly abbreviated specification SPEC is parsed by + + 1. Attempt to parse SPEC as a possibly abbreviated inst-list. + + 2. If that fails, attempt to parse SPEC as a cons of a locale + and an (abbreviated) inst-list. + + 3. If that fails, SPEC is invalid. + + A possibly abbreviated inst-list INST-LIST is parsed by + + 1. Attempt to parse INST-LIST as a possibly abbreviated + inst-pair. + + 2. If that fails, attempt to parse INST-LIST as a list of + (abbreviated) inst-pairs. + + 3. If that fails, INST-LIST is invalid. + + A possibly abbreviated inst-pair INST-PAIR is parsed by + + 1. Check if INST-PAIR is `valid-instantiator-p'. + + 2. If not, check if INST-PAIR is a cons of something that is a + tag, ie, `valid-specifier-tag-p', and something that is + `valid-instantiator-p'. + + 3. If not, check if INST-PAIR is a cons of a list of tags and + something that is `valid-instantiator-p'. + + 4. Otherwise, INST-PAIR is invalid. + + In summary, this function generally prefers more abbreviated forms. + + +File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers + +Retrieving the Specifications from a Specifier +============================================== + + - Function: specifier-spec-list specifier &optional locale tag-set + exact-p + This function returns the spec-list of specifications for + SPECIFIER in LOCALE. + + If LOCALE is a particular locale (a window, buffer, frame, device, + or the symbol `global'), a spec-list consisting of the + specification for that locale will be returned. + + If LOCALE is a locale type (i.e. one of the symbols `window', + `buffer', `frame', or `device'), a spec-list of the specifications + for all locales of that type will be returned. + + If LOCALE is `nil' or the symbol `all', a spec-list of all + specifications in SPECIFIER will be returned. + + LOCALE can also be a list of locales, locale types, and/or `all'; + the result is as if `specifier-spec-list' were called on each + element of the list and the results concatenated together. + + Only instantiators where TAG-SET (a list of zero or more tags) is + a subset of (or possibly equal to) the instantiator's tag set are + returned. (The default value of `nil' is a subset of all tag sets, + so in this case no instantiators will be screened out.) If EXACT-P + is non-`nil', however, TAG-SET must be equal to an instantiator's + tag set for the instantiator to be returned. + + - Function: specifier-specs specifier &optional locale tag-set exact-p + This function returns the specification(s) for SPECIFIER in LOCALE. + + If LOCALE is a single locale or is a list of one element + containing a single locale, then a "short form" of the + instantiators for that locale will be returned. Otherwise, this + function is identical to `specifier-spec-list'. + + The "short form" is designed for readability and not for ease of + use in Lisp programs, and is as follows: + + 1. If there is only one instantiator, then an inst-pair (i.e. + cons of tag and instantiator) will be returned; otherwise a + list of inst-pairs will be returned. + + 2. For each inst-pair returned, if the instantiator's tag is + `any', the tag will be removed and the instantiator itself + will be returned instead of the inst-pair. + + 3. If there is only one instantiator, its value is `nil', and + its tag is `any', a one-element list containing `nil' will be + returned rather than just `nil', to distinguish this case + from there being no instantiators at all. + + + - Function: specifier-fallback specifier + This function returns the fallback value for SPECIFIER. Fallback + values are provided by the C code for certain built-in specifiers + to make sure that instancing won't fail even if all specs are + removed from the specifier, or to implement simple inheritance + behavior (e.g. this method is used to ensure that faces other than + `default' inherit their attributes from `default'). By design, + you cannot change the fallback value, and specifiers created with + `make-specifier' will never have a fallback (although a similar, + Lisp-accessible capability may be provided in the future to allow + for inheritance). + + The fallback value will be an inst-list that is instanced like any + other inst-list, a specifier of the same type as SPECIFIER + (results in inheritance), or `nil' for no fallback. + + When you instance a specifier, you can explicitly request that the + fallback not be consulted. (The C code does this, for example, when + merging faces.) See `specifier-instance'. + + +File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers + +Working With Specifier Tags +=========================== + +A specifier tag set is an entity that is attached to an instantiator +and can be used to restrict the scope of that instantiator to a +particular device class or device type and/or to mark instantiators +added by a particular package so that they can be later removed. + + A specifier tag set consists of a list of zero or more specifier +tags, each of which is a symbol that is recognized by XEmacs as a tag. +(The valid device types and device classes are always tags, as are any +tags defined by `define-specifier-tag'.) It is called a "tag set" (as +opposed to a list) because the order of the tags or the number of times +a particular tag occurs does not matter. + + Each tag has a predicate associated with it, which specifies whether +that tag applies to a particular device. The tags which are device +types and classes match devices of that type or class. User-defined +tags can have any predicate, or none (meaning that all devices match). +When attempting to instance a specifier, a particular instantiator is +only considered if the device of the domain being instanced over matches +all tags in the tag set attached to that instantiator. + + Most of the time, a tag set is not specified, and the instantiator +gets a null tag set, which matches all devices. + + - Function: valid-specifier-tag-p tag + This function returns non-`nil' if TAG is a valid specifier tag. + + - Function: valid-specifier-tag-set-p tag-set + This function returns non-`nil' if TAG-SET is a valid specifier + tag set. + + - Function: canonicalize-tag-set tag-set + This function canonicalizes the given tag set. Two canonicalized + tag sets can be compared with `equal' to see if they represent the + same tag set. (Specifically, canonicalizing involves sorting by + symbol name and removing duplicates.) + + - Function: device-matches-specifier-tag-set-p device tag-set + This function returns non-`nil' if DEVICE matches specifier tag + set TAG-SET. This means that DEVICE matches each tag in the tag + set. + + - Function: define-specifier-tag tag &optional predicate + This function defines a new specifier tag. If PREDICATE is + specified, it should be a function of one argument (a device) that + specifies whether the tag matches that particular device. If + PREDICATE is omitted, the tag matches all devices. + + You can redefine an existing user-defined specifier tag. However, + you cannot redefine the built-in specifier tags (the device types + and classes) or the symbols `nil', `t', `all', or `global'. + + - Function: device-matching-specifier-tag-list &optional device + This function returns a list of all specifier tags matching + DEVICE. DEVICE defaults to the selected device if omitted. + + - Function: specifier-tag-list + This function returns a list of all currently-defined specifier + tags. This includes the built-in ones (the device types and + classes). + + - Function: specifier-tag-predicate tag + This function returns the predicate for the given specifier tag. + + +File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Examples, Prev: Specifier Tag Functions, Up: Specifiers + +Functions for Instancing a Specifier +==================================== + + - Function: specifier-instance specifier &optional domain default + no-fallback + This function instantiates SPECIFIER (returns its value) in + DOMAIN. If no instance can be generated for this domain, return + DEFAULT. + + DOMAIN should be a window, frame, or device. Other values that + are legal as a locale (e.g. a buffer) are not valid as a domain + because they do not provide enough information to identify a + particular device (see `valid-specifier-domain-p'). DOMAIN + defaults to the selected window if omitted. + + "Instantiating" a specifier in a particular domain means + determining the specifier's "value" in that domain. This is + accomplished by searching through the specifications in the + specifier that correspond to all locales that can be derived from + the given domain, from specific to general. In most cases, the + domain is an Emacs window. In that case specifications are + searched for as follows: + + 1. A specification whose locale is the window itself; + + 2. A specification whose locale is the window's buffer; + + 3. A specification whose locale is the window's frame; + + 4. A specification whose locale is the window's frame's device; + + 5. A specification whose locale is the symbol `global'. + + If all of those fail, then the C-code-provided fallback value for + this specifier is consulted (see `specifier-fallback'). If it is + an inst-list, then this function attempts to instantiate that list + just as when a specification is located in the first five steps + above. If the fallback is a specifier, `specifier-instance' is + called recursively on this specifier and the return value used. + Note, however, that if the optional argument NO-FALLBACK is + non-`nil', the fallback value will not be consulted. + + Note that there may be more than one specification matching a + particular locale; all such specifications are considered before + looking for any specifications for more general locales. Any + particular specification that is found may be rejected because it + is tagged to a particular device class (e.g. `color') or device + type (e.g. `x') or both and the device for the given domain does + not match this, or because the specification is not valid for the + device of the given domain (e.g. the font or color name does not + exist for this particular X server). + + The returned value is dependent on the type of specifier. For + example, for a font specifier (as returned by the `face-font' + function), the returned value will be a font-instance object. For + images, the returned value will be a string, pixmap, or subwindow. + + - Function: specifier-matching-instance specifier matchspec &optional + domain default no-fallback + This function returns an instance for SPECIFIER in DOMAIN that + matches MATCHSPEC. If no instance can be generated for DOMAIN, + return DEFAULT. + + This function is identical to `specifier-instance' except that a + specification will only be considered if it matches MATCHSPEC. + The definition of "match," and allowed values for MATCHSPEC, are + dependent on the particular type of specifier. Here are some + examples: + + * For chartable (e.g. display table) specifiers, MATCHSPEC + should be a character, and the specification (a chartable) + must give a value for that character in order to be + considered. This allows you to specify, _e.g._, a + buffer-local display table that only gives values for + particular characters. All other characters are handled as + if the buffer-local display table is not there. (Chartable + specifiers are not yet implemented.) + + * For font specifiers, MATCHSPEC should be a charset, and the + specification (a font string) must have a registry that + matches the charset's registry. (This only makes sense with + Mule support.) This makes it easy to choose a font that can + display a particular character. (This is what redisplay + does, in fact.) + + - Function: specifier-instance-from-inst-list specifier domain + inst-list &optional default + This function attempts to convert a particular inst-list into an + instance. This attempts to instantiate INST-LIST in the given + DOMAIN, as if INST-LIST existed in a specification in SPECIFIER. + If the instantiation fails, DEFAULT is returned. In most + circumstances, you should not use this function; use + `specifier-instance' instead. + + +File: lispref.info, Node: Specifier Examples, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers + +Examples of Specifier Usage +=========================== + +Now let us present an example to clarify the theoretical discussions we +have been through. In this example, we will use the general specifier +functions for clarity. Keep in mind that many types of specifiers, and +some other types of objects that are associated with specifiers (e.g. +faces), provide convenience functions making it easier to work with +objects of that type. + + Let us consider the background color of the default face. A +specifier is used to specify how that color will appear in different +domains. First, let's retrieve the specifier: + + (setq sp (face-property 'default 'background)) + => # + + (specifier-specs sp) + => ((# (nil . "forest green")) + (# (nil . "hot pink")) + (# (nil . "puke orange") + (nil . "moccasin")) + (# (nil . "magenta")) + (global ((tty) . "cyan") (nil . "white")) + ) + + Then, say we want to determine what the background color of the +default face is for the window currently displaying the buffer +`*scratch*'. We call + + (get-buffer-window "*scratch*") + => # + (window-frame (get-buffer-window "*scratch*")) + => # + (specifier-instance sp (get-buffer-window "*scratch*")) + => # + + Note that we passed a window to `specifier-instance', not a buffer. +We cannot pass a buffer because a buffer by itself does not provide +enough information. The buffer might not be displayed anywhere at all, +or could be displayed in many different frames on different devices. + + The result is arrived at like this: + + 1. First, we look for a specification matching the buffer displayed + in the window, i.e. `*scratch*'. There are none, so we proceed. + + 2. Then, we look for a specification matching the window itself. + Again, there are none. + + 3. Then, we look for a specification matching the window's frame. The + specification `(# . "puke orange")' is + found. We call the instantiation method for colors, passing it the + locale we were searching over (i.e. the window, in this case) and + the instantiator (`"puke orange"'). However, the particular device + which this window is on (let's say it's an X connection) doesn't + recognize the color `"puke orange"', so the specification is + rejected. + + 4. So we continue looking for a specification matching the window's + frame. We find `(# . "moccasin")'. Again, + we call the instantiation method for colors. This time, the X + server our window is on recognizes the color `moccasin', and so the + instantiation method succeeds and returns a color instance. + + Here's another example, which implements something like GNU Emacs's +"frame-local" variables. + + ;; Implementation + + ;; There are probably better ways to write this macro + ;; Heaven help you if VAR is a buffer-local; you will become very + ;; confused. Probably should error on that. + (defmacro define-frame-local-variable (var) + "Make the unbound symbol VAR become a frame-local variable." + (let ((val (if (boundp var) (symbol-value var) nil))) + `(progn + (setq ,var (make-specifier 'generic)) + (add-spec-to-specifier ,var ',val 'global)))) + + ;; I'm not real happy about this terminology, how can `setq' be a defun? + ;; But `frame-set' would have people writing "(frame-set 'foo value)". + (defun frame-setq (var value &optional frame) + "Set the local value of VAR to VALUE in FRAME. + + FRAME defaults to the selected frame." + (and frame (not (framep frame)) + (error 'invalid-argument "FRAME must be a frame", frame)) + (add-spec-to-specifier var value (or frame (selected-frame)))) + + (defun frame-value (var &optional frame) + "Get the local value of VAR in FRAME. + + FRAME defaults to the selected frame." + (and frame (not (framep frame)) + (error 'invalid-argument "FRAME must be a frame", frame)) + ;; this is not just a map from frames to values; it also falls back + ;; to the global value + (specifier-instance var (or frame (selected-frame)))) + + ;; for completeness + (defun frame-set-default (var value) + "Set the default value of frame-local variable VAR to VALUE." + (add-spec-to-specifier var value 'global)) + + (defun frame-get-default (var) + "Get the default value of frame-local variable VAR." + (car (specifier-specs var 'global))) + + Now you can execute the above definitions (eg, with `eval-last-sexp') +and switch to `*scratch*' to play. Things will work differently if you +already have a variable named `foo'. + + ;; Usage + + foo + error--> Symbol's value as variable is void: foo + + (define-frame-local-variable foo) + => nil + + ;; the value of foo is a specifier, which is an opaque object; + ;; you must use accessor functions to get values + + foo + => # + + ;; since no frame-local value is set, the global value (which is the + ;; constant `nil') is returned + (frame-value foo) + => nil + + ;; get the default explicitly + (frame-get-default foo) + => nil + + ;; get the whole specification list + (specifier-specs foo 'global) + => (nil) + + ;; give foo a frame-local value + + (frame-setq foo 'bar) + => nil + + ;; access foo in several ways + + ;; Note that the print function for this kind of specifier only + ;; gives you the global setting. To get the full list of specs for + ;; debugging or study purposes, you must use specifier-specs or + ;; specifier-spec-list. + foo + => # + + ;; get the whole specification list + (specifier-specs foo) + => ((# (nil . bar)) (global (nil))) + + ;; get the frame-local value + (frame-value foo) + => bar + + ;; get the default explicitly + (frame-get-default foo) + => nil + + ;; Switch to another frame and evaluate: + ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET + => baz + + ;; Switch back. + ;; C-x 5 o + (specifier-specs foo) + => ((# (nil . baz)) + (# (nil . bar)) + (global (nil))) + + (frame-value foo) + => bar + + (frame-get-default foo) + => nil + + Note that since specifiers generalize both frame-local and +buffer-local variables in a sensible way, XEmacs is not likely to put a +high priority on implementing frame-local variables. In fact, some +developers think that frame-local variables are evil for the same +reason that buffer-local variables are evil: the declaration is both +global and invisible. That is, you cannot tell whether a variable is +"normal," buffer-local, or frame-local just by looking at it. So if +you have namespace management problems, and some other Lisp package +happens to use a variable name that you already declared frame- or +buffer-local, weird stuff happens, and it is extremely hard to track +down. + + +File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Examples, Up: Specifiers + +Creating New Specifier Objects +============================== + + - Function: make-specifier type + This function creates a new specifier. + + A specifier is an object that can be used to keep track of a + property whose value can be per-buffer, per-window, per-frame, or + per-device, and can further be restricted to a particular + device-type or device-class. Specifiers are used, for example, + for the various built-in properties of a face; this allows a face + to have different values in different frames, buffers, etc. For + more information, see `specifier-instance', `specifier-specs', and + `add-spec-to-specifier'; or, for a detailed description of + specifiers, including how they are instantiated over a particular + domain (i.e. how their value in that domain is determined), see + the chapter on specifiers in the XEmacs Lisp Reference Manual. + + TYPE specifies the particular type of specifier, and should be one + of the symbols `generic', `integer', `natnum', `boolean', `color', + `font', `image', `face-boolean', or `toolbar'. + + For more information on particular types of specifiers, see the + functions `make-generic-specifier', `make-integer-specifier', + `make-natnum-specifier', `make-boolean-specifier', + `make-color-specifier', `make-font-specifier', + `make-image-specifier', `make-face-boolean-specifier', and + `make-toolbar-specifier'. + + - Function: make-specifier-and-init type spec-list &optional + dont-canonicalize + This function creates and initializes a new specifier. + + This is a convenience API combining `make-specifier' and + `set-specifier' that allows you to create a specifier and add + specs to it at the same time. TYPE specifies the specifier type. + Allowed types are as for `make-specifier'. + + SPEC-LIST supplies the specification(s) to be added to the + specifier. Any abbreviation of the full spec-list form accepted + by `canonicalize-spec-list' may be used. However, if the optional + argument DONT-CANONICALIZE is non-`nil', canonicalization is not + performed, and the SPEC-LIST must already be in full form. + + - Function: make-integer-specifier spec-list + Return a new `integer' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for integer specifiers are integers. + + - Function: make-boolean-specifier spec-list + Return a new `boolean' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for boolean specifiers are `t' and `nil'. + + - Function: make-natnum-specifier spec-list + Return a new `natnum' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for natnum specifiers are non-negative + integers. + + - Function: make-generic-specifier spec-list + Return a new `generic' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for generic specifiers are all Lisp values. + They are returned back unchanged when a specifier is instantiated. + + - Function: make-display-table-specifier spec-list + Return a new `display-table' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for display-table specifiers are described in + detail in the doc string for `current-display-table' (*note Active + Display Table::). + + +File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers + +Functions for Checking the Validity of Specifier Components +=========================================================== + + - Function: valid-specifier-domain-p domain + This function returns non-`nil' if DOMAIN is a valid specifier + domain. A domain is used to instance a specifier (i.e. determine + the specifier's value in that domain). Valid domains are a + window, frame, or device. (`nil' is not valid.) + + - Function: valid-specifier-locale-p locale + This function returns non-`nil' if LOCALE is a valid specifier + locale. Valid locales are a device, a frame, a window, a buffer, + and `global'. (`nil' is not valid.) + + - Function: valid-specifier-locale-type-p locale-type + Given a specifier LOCALE-TYPE, this function returns non-`nil' if + it is valid. Valid locale types are the symbols `global', + `device', `frame', `window', and `buffer'. (Note, however, that in + functions that accept either a locale or a locale type, `global' + is considered an individual locale.) + + - Function: valid-specifier-type-p specifier-type + Given a SPECIFIER-TYPE, this function returns non-`nil' if it is + valid. Valid types are `generic', `integer', `boolean', `color', + `font', `image', `face-boolean', and `toolbar'. + + - Function: valid-specifier-tag-p tag + This function returns non-`nil' if TAG is a valid specifier tag. + + - Function: valid-instantiator-p instantiator specifier-type + This function returns non-`nil' if INSTANTIATOR is valid for + SPECIFIER-TYPE. + + - Function: valid-inst-list-p inst-list type + This function returns non-`nil' if INST-LIST is valid for + specifier type TYPE. + + - Function: valid-spec-list-p spec-list type + This function returns non-`nil' if SPEC-LIST is valid for + specifier type TYPE. + + - Function: check-valid-instantiator instantiator specifier-type + This function signals an error if INSTANTIATOR is invalid for + SPECIFIER-TYPE. + + - Function: check-valid-inst-list inst-list type + This function signals an error if INST-LIST is invalid for + specifier type TYPE. + + - Function: check-valid-spec-list spec-list type + This function signals an error if SPEC-LIST is invalid for + specifier type TYPE. + + +File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers + +Other Functions for Working with Specifications in a Specifier +============================================================== + + - Function: copy-specifier specifier &optional dest locale tag-set + exact-p how-to-add + This function copies SPECIFIER to DEST, or creates a new one if + DEST is `nil'. + + If DEST is `nil' or omitted, a new specifier will be created and + the specifications copied into it. Otherwise, the specifications + will be copied into the existing specifier in DEST. + + If LOCALE is `nil' or the symbol `all', all specifications will be + copied. If LOCALE is a particular locale, the specification for + that particular locale will be copied. If LOCALE is a locale + type, the specifications for all locales of that type will be + copied. LOCALE can also be a list of locales, locale types, + and/or `all'; this is equivalent to calling `copy-specifier' for + each of the elements of the list. See `specifier-spec-list' for + more information about LOCALE. + + Only instantiators where TAG-SET (a list of zero or more tags) is + a subset of (or possibly equal to) the instantiator's tag set are + copied. (The default value of `nil' is a subset of all tag sets, + so in this case no instantiators will be screened out.) If EXACT-P + is non-`nil', however, TAG-SET must be equal to an instantiator's + tag set for the instantiator to be copied. + + Optional argument HOW-TO-ADD specifies what to do with existing + specifications in DEST. If `nil', then whichever locales or locale + types are copied will first be completely erased in DEST. + Otherwise, it is the same as in `add-spec-to-specifier'. + + - Function: remove-specifier specifier &optional locale tag-set exact-p + This function removes specification(s) for SPECIFIER. + + If LOCALE is a particular locale (a buffer, window, frame, device, + or the symbol `global'), the specification for that locale will be + removed. + + If instead, LOCALE is a locale type (i.e. a symbol `buffer', + `window', `frame', or `device'), the specifications for all + locales of that type will be removed. + + If LOCALE is `nil' or the symbol `all', all specifications will be + removed. + + LOCALE can also be a list of locales, locale types, and/or `all'; + this is equivalent to calling `remove-specifier' for each of the + elements in the list. + + Only instantiators where TAG-SET (a list of zero or more tags) is + a subset of (or possibly equal to) the instantiator's tag set are + removed. (The default value of `nil' is a subset of all tag sets, + so in this case no instantiators will be screened out.) If EXACT-P + is non-`nil', however, TAG-SET must be equal to an instantiator's + tag set for the instantiator to be removed. + + - Function: map-specifier specifier func &optional locale maparg + This function applies FUNC to the specification(s) for LOCALE in + SPECIFIER. + + If optional LOCALE is a locale, FUNC will be called for that + locale. If LOCALE is a locale type, FUNC will be mapped over all + locales of that type. If LOCALE is `nil' or the symbol `all', + FUNC will be mapped over all locales in SPECIFIER. + + Optional MS-MAPARG will be passed to MS-FUNC. + + FUNC is called with four arguments: the SPECIFIER, the locale + being mapped over, the inst-list for that locale, and the optional + MAPARG. If any invocation of FUNC returns non-`nil', the mapping + will stop and the returned value becomes the value returned from + `map-specifier'. Otherwise, `map-specifier' returns `nil'. + + - Function: specifier-locale-type-from-locale locale + Given a specifier LOCALE, this function returns its type. + + +File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top + +Faces and Window-System Objects +******************************* + +* Menu: + +* Faces:: Controlling the way text looks. +* Fonts:: Controlling the typeface of text. +* Colors:: Controlling the color of text and pixmaps. + + +File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects + +Faces +===== + +A "face" is a named collection of graphical properties: font, +foreground color, background color, background pixmap, optional +underlining, and (on TTY devices) whether the text is to be highlighted, +dimmed, blinking, or displayed in reverse video. Faces control the +display of text on the screen. Every face has a name, which is a symbol +such as `default' or `modeline'. + + Each built-in property of a face is controlled using a specifier, +which allows it to have separate values in particular buffers, frames, +windows, and devices and to further vary according to device type (X or +TTY) and device class (color, mono, or grayscale). *Note Specifiers::, +for more information. + + The face named `default' is used for ordinary text. The face named +`modeline' is used for displaying the modeline. The face named +`highlight' is used for highlighted extents (*note Extents::). The +faces named `left-margin' and `right-margin' are used for the left and +right margin areas, respectively (*note Annotations::). The face named +`zmacs-region' is used for the highlighted region between point and +mark. + +* Menu: + +* Merging Faces:: How XEmacs decides which face to use + for a character. +* Basic Face Functions:: How to define and examine faces. +* Face Properties:: How to access and modify a face's properties. +* Face Convenience Functions:: Convenience functions for accessing + particular properties of a face. +* Other Face Display Functions:: Other functions pertaining to how a + a face appears. + + +File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces + +Merging Faces for Display +------------------------- + +Here are all the ways to specify which face to use for display of text: + + * With defaults. Each frame has a "default face", which is used for + all text that doesn't somehow specify another face. The face named + `default' applies to the text area, while the faces `left-margin' + and `right-margin' apply to the left and right margin areas. + + * With text properties. A character may have a `face' property; if + so, it's displayed with that face. (Text properties are actually + implemented in terms of extents.) *Note Text Properties::. + + * With extents. An extent may have a `face' property, which applies + to all the text covered by the extent; in addition, if the + `highlight' property is set, the `highlight' property applies when + the mouse moves over the extent or if the extent is explicitly + highlighted. *Note Extents::. + + * With annotations. Annotations that are inserted into a buffer can + specify their own face. (Annotations are actually implemented in + terms of extents.) *Note Annotations::. + + If these various sources together specify more than one face for a +particular character, XEmacs merges the properties of the various faces +specified. Extents, text properties, and annotations all use the same +underlying representation (as extents). When multiple extents cover one +character, an extent with higher priority overrides those with lower +priority. *Note Extents::. If no extent covers a particular character, +the `default' face is used. + + If a background pixmap is specified, it determines what will be +displayed in the background of text characters. If the background +pixmap is actually a pixmap, with its colors specified, those colors are +used; if it is a bitmap, the face's foreground and background colors are +used to color it. + + +File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces + +Basic Functions for Working with Faces +-------------------------------------- + +The properties a face can specify include the font, the foreground +color, the background color, the background pixmap, the underlining, +the display table, and (for TTY devices) whether the text is to be +highlighted, dimmed, blinking, or displayed in reverse video. The face +can also leave these unspecified, causing them to assume the value of +the corresponding property of the `default' face. + + Here are the basic primitives for working with faces. + + - Function: make-face name &optional doc-string temporary + This function defines and returns a new face named NAME, initially + with all properties unspecified. It does nothing if there is + already a face named NAME. Optional argument DOC-STRING specifies + an explanatory string used for descriptive purposes. If optional + argument TEMPORARY is non-`nil', the face will automatically + disappear when there are no more references to it anywhere in text + or Lisp code (otherwise, the face will continue to exist + indefinitely even if it is not used). + + - Function: face-list &optional temporary + This function returns a list of the names of all defined faces. If + TEMPORARY is `nil', only the permanent faces are included. If it + is `t', only the temporary faces are included. If it is any other + non-`nil' value both permanent and temporary are included. + + - Function: facep object + This function returns `t' if OBJECT is a face, else `nil'. + + - Function: copy-face old-face new-name &optional locale tag-set + exact-p how-to-add + This function defines a new face named NEW-NAME which is a copy of + the existing face named OLD-FACE. If there is already a face + named NEW-NAME, then it alters the face to have the same + properties as OLD-FACE. + + LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of + the old face rather than the whole face, and are as in + `copy-specifier' (*note Specifiers::). + + +File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces + +Face Properties +--------------- + +You can examine and modify the properties of an existing face with the +following functions. + + The following symbols have predefined meanings: + +`foreground' + The foreground color of the face. + +`background' + The background color of the face. + +`font' + The font used to display text covered by this face. + +`display-table' + The display table of the face. + +`background-pixmap' + The pixmap displayed in the background of the face. Only used by + faces on X devices. + +`underline' + Underline all text covered by this face. + +`highlight' + Highlight all text covered by this face. Only used by faces on TTY + devices. + +`dim' + Dim all text covered by this face. Only used by faces on TTY + devices. + +`blinking' + Blink all text covered by this face. Only used by faces on TTY + devices. + +`reverse' + Reverse the foreground and background colors. Only used by faces + on TTY devices. + +`doc-string' + Description of what the face's normal use is. NOTE: This is not a + specifier, unlike all the other built-in properties, and cannot + contain locale-specific values. + + - Function: set-face-property face property value &optional locale + tag-set how-to-add + This function changes a property of a FACE. + + For built-in properties, the actual value of the property is a + specifier and you cannot change this; but you can change the + specifications within the specifier, and that is what this + function will do. For user-defined properties, you can use this + function to either change the actual value of the property or, if + this value is a specifier, change the specifications within it. + + If PROPERTY is a built-in property, the specifications to be added + to this property can be supplied in many different ways: + + If VALUE is a simple instantiator (e.g. a string naming a + font or color) or a list of instantiators, then the + instantiator(s) will be added as a specification of the + property for the given LOCALE (which defaults to `global' if + omitted). + + If VALUE is a list of specifications (each of which is a cons + of a locale and a list of instantiators), then LOCALE must be + `nil' (it does not make sense to explicitly specify a locale + in this case), and specifications will be added as given. + + If VALUE is a specifier (as would be returned by + `face-property' if no LOCALE argument is given), then some or + all of the specifications in the specifier will be added to + the property. In this case, the function is really + equivalent to `copy-specifier' and LOCALE has the same + semantics (if it is a particular locale, the specification + for the locale will be copied; if a locale type, + specifications for all locales of that type will be copied; + if `nil' or `all', then all specifications will be copied). + + HOW-TO-ADD should be either `nil' or one of the symbols `prepend', + `append', `remove-tag-set-prepend', `remove-tag-set-append', + `remove-locale', `remove-locale-type', or `remove-all'. See + `copy-specifier' and `add-spec-to-specifier' for a description of + what each of these means. Most of the time, you do not need to + worry about this argument; the default behavior usually is fine. + + In general, it is OK to pass an instance object (e.g. as returned + by `face-property-instance') as an instantiator in place of an + actual instantiator. In such a case, the instantiator used to + create that instance object will be used (for example, if you set + a font-instance object as the value of the `font' property, then + the font name used to create that object will be used instead). + If some cases, however, doing this conversion does not make sense, + and this will be noted in the documentation for particular types + of instance objects. + + If PROPERTY is not a built-in property, then this function will + simply set its value if LOCALE is `nil'. However, if LOCALE is + given, then this function will attempt to add VALUE as the + instantiator for the given LOCALE, using `add-spec-to-specifier'. + If the value of the property is not a specifier, it will + automatically be converted into a `generic' specifier. + + - Function: remove-face-property face property &optional locale + tag-set exact-p + This function removes a property of a FACE. + + For built-in properties, this is analogous to `remove-specifier'. + For more information, *Note Other Specification Functions::. + + When PROPERTY is not a built-in property, this function will just + remove its value if LOCALE is `nil' or `all'. However, if LOCALE + is other than that, this function will attempt to remove VALUE as + the instantiator for the given LOCALE with `remove-specifier'. If + the value of the property is not a specifier, it will be converted + into a `generic' specifier automatically. + + - Function: face-property face property &optional locale tag-set + exact-p + This function returns FACE's value of the given PROPERTY. + + If LOCALE is omitted, the FACE's actual value for PROPERTY will be + returned. For built-in properties, this will be a specifier + object of a type appropriate to the property (e.g. a font or color + specifier). For other properties, this could be anything. + + If LOCALE is supplied, then instead of returning the actual value, + the specification(s) for the given locale or locale type will be + returned. This will only work if the actual value of PROPERTY is + a specifier (this will always be the case for built-in properties, + but not or not may apply to user-defined properties). If the + actual value of PROPERTY is not a specifier, this value will + simply be returned regardless of LOCALE. + + The return value will be a list of instantiators (e.g. strings + specifying a font or color name), or a list of specifications, + each of which is a cons of a locale and a list of instantiators. + Specifically, if LOCALE is a particular locale (a buffer, window, + frame, device, or `global'), a list of instantiators for that + locale will be returned. Otherwise, if LOCALE is a locale type + (one of the symbols `buffer', `window', `frame', or `device'), the + specifications for all locales of that type will be returned. + Finally, if LOCALE is `all', the specifications for all locales of + all types will be returned. + + The specifications in a specifier determine what the value of + PROPERTY will be in a particular "domain" or set of circumstances, + which is typically a particular Emacs window along with the buffer + it contains and the frame and device it lies within. The value is + derived from the instantiator associated with the most specific + locale (in the order buffer, window, frame, device, and `global') + that matches the domain in question. In other words, given a + domain (i.e. an Emacs window, usually), the specifier for PROPERTY + will first be searched for a specification whose locale is the + buffer contained within that window; then for a specification + whose locale is the window itself; then for a specification whose + locale is the frame that the window is contained within; etc. The + first instantiator that is valid for the domain (usually this + means that the instantiator is recognized by the device [i.e. the + X server or TTY device] that the domain is on). The function + `face-property-instance' actually does all this, and is used to + determine how to display the face. + + - Function: face-property-instance face property &optional domain + default no-fallback + This function returns the instance of FACE's PROPERTY in the + specified DOMAIN. + + Under most circumstances, DOMAIN will be a particular window, and + the returned instance describes how the specified property + actually is displayed for that window and the particular buffer in + it. Note that this may not be the same as how the property + appears when the buffer is displayed in a different window or + frame, or how the property appears in the same window if you + switch to another buffer in that window; and in those cases, the + returned instance would be different. + + The returned instance will typically be a color-instance, + font-instance, or pixmap-instance object, and you can query it + using the appropriate object-specific functions. For example, you + could use `color-instance-rgb-components' to find out the RGB + (red, green, and blue) components of how the `background' property + of the `highlight' face is displayed in a particular window. The + results might be different from the results you would get for + another window (perhaps the user specified a different color for + the frame that window is on; or perhaps the same color was + specified but the window is on a different X server, and that X + server has different RGB values for the color from this one). + + DOMAIN defaults to the selected window if omitted. + + DOMAIN can be a frame or device, instead of a window. The value + returned for a such a domain is used in special circumstances when + a more specific domain does not apply; for example, a frame value + might be used for coloring a toolbar, which is conceptually + attached to a frame rather than a particular window. The value is + also useful in determining what the value would be for a + particular window within the frame or device, if it is not + overridden by a more specific specification. + + If PROPERTY does not name a built-in property, its value will + simply be returned unless it is a specifier object, in which case + it will be instanced using `specifier-instance'. + + Optional arguments DEFAULT and NO-FALLBACK are the same as in + `specifier-instance'. *Note Specifiers::. + + +File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces + +Face Convenience Functions +-------------------------- + + - Command: set-face-foreground face color &optional locale tag-set + how-to-add + - Command: set-face-background face color &optional locale tag-set + how-to-add + These functions set the foreground (respectively, background) + color of face FACE to COLOR. The argument COLOR should be a + string (the name of a color) or a color object as returned by + `make-color' (*note Colors::). + + - Command: set-face-background-pixmap face pixmap &optional locale + tag-set how-to-add + This function sets the background pixmap of face FACE to PIXMAP. + The argument PIXMAP should be a string (the name of a bitmap or + pixmap file; the directories listed in the variable + `x-bitmap-file-path' will be searched) or a glyph object as + returned by `make-glyph' (*note Glyphs::). The argument may also + be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT + are the size in pixels, and DATA is a string, containing the raw + bits of the bitmap. + + - Command: set-face-font face font &optional locale tag-set how-to-add + This function sets the font of face FACE. The argument FONT + should be a string or a font object as returned by `make-font' + (*note Fonts::). + + - Command: set-face-underline-p face underline-p &optional locale + tag-set how-to-add + This function sets the underline property of face FACE. + + - Function: face-foreground face &optional locale tag-set exact-p + - Function: face-background face &optional locale tag-set exact-p + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap face &optional locale tag-set + exact-p + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font face &optional locale tag-set exact-p + This function returns the font specifier of face FACE. (Note: + This is not the same as the function `face-font' in FSF Emacs.) + + *Note Fonts::. + + - Function: face-font-name face &optional domain + This function returns the name of the font of face FACE, or `nil' + if it is unspecified. This is basically equivalent to `(font-name + (face-font FACE) DOMAIN)' except that it does not cause an error + if FACE's font is `nil'. (This function is named `face-font' in + FSF Emacs.) + + - Function: face-underline-p face &optional locale + This function returns the underline property of face FACE. + + - Function: face-foreground-instance face &optional domain + - Function: face-background-instance face &optional domain + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap-instance face &optional domain + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font-instance face &optional domain + This function returns the font specifier of face FACE. *Note + Fonts::. + + +File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces + +Other Face Display Functions +---------------------------- + + - Command: invert-face face &optional locale + Swap the foreground and background colors of face FACE. If the + face doesn't specify both foreground and background, then its + foreground and background are set to the default background and + foreground. + + - Function: face-equal face1 face2 &optional domain + This returns `t' if the faces FACE1 and FACE2 will display in the + same way. DOMAIN is as in `face-property-instance'. + + - Function: face-differs-from-default-p face &optional domain + This returns `t' if the face FACE displays differently from the + default face. DOMAIN is as in `face-property-instance'. + + +File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects + +Fonts +===== + +This section describes how to work with font specifier and font +instance objects, which encapsulate fonts in the window system. + +* Menu: + +* Font Specifiers:: Specifying how a font will appear. +* Font Instances:: What a font specifier gets instanced as. +* Font Instance Names:: The name of a font instance. +* Font Instance Size:: The size of a font instance. +* Font Instance Characteristics:: Display characteristics of font instances. +* Font Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a font specifier. + + +File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts + +Font Specifiers +--------------- + + - Function: font-specifier-p object + This predicate returns `t' if OBJECT is a font specifier, and + `nil' otherwise. + + - Function: make-font-specifier spec-list + Return a new `font' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Valid instantiators for font specifiers are: + + * A string naming a font (e.g. under X this might be + "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a + 14-point upright medium-weight Courier font). + + * A font instance (use that instance directly if the device + matches, or use the string that generated it). + + * A vector of no elements (only on TTY's; this means to set no + font at all, thus using the "natural" font of the terminal's + text). + + * A vector of one element (a face to inherit from). + + +File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts + +Font Instances +-------------- + + - Function: font-instance-p object + This predicate returns `t' if OBJECT is a font instance, and `nil' + otherwise. + + - Function: make-font-instance name &optional device noerror + This function creates a new font-instance object of the specified + name. DEVICE specifies the device this object applies to and + defaults to the selected device. An error is signalled if the + font is unknown or cannot be allocated; however, if NOERROR is + non-`nil', `nil' is simply returned in this case. + + The returned object is a normal, first-class lisp object. The way + you "deallocate" the font is the way you deallocate any other lisp + object: you drop all pointers to it and allow it to be garbage + collected. When these objects are GCed, the underlying X data is + deallocated as well. + + +File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts + +Font Instance Names +------------------- + + - Function: list-fonts pattern &optional device + This function returns a list of font names matching the given + pattern. DEVICE specifies which device to search for names, and + defaults to the currently selected device. + + - Function: font-instance-name font-instance + This function returns the name used to allocate FONT-INSTANCE. + + - Function: font-instance-truename font-instance + This function returns the canonical name of the given font + instance. Font names are patterns which may match any number of + fonts, of which the first found is used. This returns an + unambiguous name for that font (but not necessarily its only + unambiguous name).