X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-33;h=20ec664b9bd414ce5eb6f4ce069245592b89ca3e;hb=39e0cb34c24ebae691454b5b8d448838c1e1b68e;hp=a7cb9888e73ed10960f91d46dd3c65036c6c2d97;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-33 b/info/lispref.info-33 index a7cb988..20ec664 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1046 +50,1123 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top +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. -Extents -******* + +File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data + +Accessing the Entire Match Data +------------------------------- + + The functions `match-data' and `set-match-data' read or write the +entire match data, all at once. + + - Function: match-data &optional integers reuse + This function returns a newly constructed list containing all the + information on what text the last search matched. Element zero is + the position of the beginning of the match for the whole + expression; element one is the position of the end of the match + for the expression. The next two elements are the positions of + the beginning and end of the match for the first subexpression, + and so on. In general, element number 2N corresponds to + `(match-beginning N)'; and element number 2N + 1 corresponds to + `(match-end N)'. + + All the elements are markers or `nil' if matching was done on a + buffer, and all are integers or `nil' if matching was done on a + string with `string-match'. However, if the optional first + argument INTEGERS is non-`nil', always use integers (rather than + markers) to represent buffer positions. + + If the optional second argument REUSE is a list, reuse it as part + of the value. If REUSE is long enough to hold all the values, and + if INTEGERS is non-`nil', no new lisp objects are created. + + As always, there must be no possibility of intervening searches + between the call to a search function and the call to `match-data' + that is intended to access the match data for that search. + + (match-data) + => (# + # + # + #) + + - Function: set-match-data match-list + This function sets the match data from the elements of MATCH-LIST, + which should be a list that was the value of a previous call to + `match-data'. + + If MATCH-LIST refers to a buffer that doesn't exist, you don't get + an error; that sets the match data in a meaningless but harmless + way. + + `store-match-data' is an alias for `set-match-data'. + + +File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data + +Saving and Restoring the Match Data +----------------------------------- + + When you call a function that may do a search, you may need to save +and restore the match data around that call, if you want to preserve the +match data from an earlier search for later use. Here is an example +that shows the problem that arises if you fail to save the match data: + + (re-search-forward "The \\(cat \\)") + => 48 + (foo) ; Perhaps `foo' does + ; more searching. + (match-end 0) + => 61 ; Unexpected result--not 48! + + You can save and restore the match data with `save-match-data': + + - Special Form: save-match-data body... + This special form executes BODY, saving and restoring the match + data around it. + + You can use `set-match-data' together with `match-data' to imitate +the effect of the special form `save-match-data'. This is useful for +writing code that can run in Emacs 18. Here is how: + + (let ((data (match-data))) + (unwind-protect + ... ; May change the original match data. + (set-match-data data))) + + Emacs automatically saves and restores the match data when it runs +process filter functions (*note Filter Functions::) and process +sentinels (*note Sentinels::). + + +File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching + +Searching and Case +================== - 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. + 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)'. - - Function: extentp object - This returns `t' if OBJECT is an extent. + +File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching + +Standard Regular Expressions Used in Editing +============================================ + + This section describes some variables that hold regular expressions +used for certain purposes in editing: + + - Variable: page-delimiter + This is the regexp describing line-beginnings that separate pages. + The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this + matches a line that starts with a formfeed character. + + The following two regular expressions should _not_ assume the match +always starts at the beginning of a line; they should not use `^' to +anchor the match. Most often, the paragraph commands do check for a +match only at the beginning of a line, which means that `^' would be +superfluous. When there is a nonzero left margin, they accept matches +that start after the left margin. In that case, a `^' would be +incorrect. However, a `^' is harmless in modes where a left margin is +never used. + + - Variable: paragraph-separate + This is the regular expression for recognizing the beginning of a + line that separates paragraphs. (If you change this, you may have + to change `paragraph-start' also.) The default value is + `"[ \t\f]*$"', which matches a line that consists entirely of + spaces, tabs, and form feeds (after its left margin). + + - Variable: paragraph-start + This is the regular expression for recognizing the beginning of a + line that starts _or_ separates paragraphs. The default value is + `"[ \t\n\f]"', which matches a line starting with a space, tab, + newline, or form feed (after its left margin). + + - Variable: sentence-end + This is the regular expression describing the end of a sentence. + (All paragraph boundaries also end sentences, regardless.) The + default value is: + + "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" + + This means a period, question mark or exclamation mark, followed + optionally by a closing parenthetical character, followed by tabs, + spaces or new lines. + + For a detailed explanation of this regular expression, see *Note + Regexp Example::. + + +File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top + +Syntax Tables +************* + + A "syntax table" specifies the syntactic textual function of each +character. This information is used by the parsing commands, the +complex movement commands, and others to determine where words, symbols, +and other syntactic constructs begin and end. The current syntax table +controls the meaning of the word motion functions (*note Word Motion::) +and the list motion functions (*note List Motion::) as well as the +functions in this chapter. * Menu: -* 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. +* Basics: Syntax Basics. Basic concepts of syntax tables. +* Desc: Syntax Descriptors. How characters are classified. +* Syntax Table Functions:: How to create, examine and alter syntax tables. +* Motion and Syntax:: Moving over characters with certain syntaxes. +* Parsing Expressions:: Parsing balanced expressions + using the syntax table. +* Standard Syntax Tables:: Syntax tables used by various major modes. +* Syntax Table Internals:: How syntax table information is stored.  -File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents +File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables -Introduction to Extents -======================= +Syntax Table Concepts +===================== - 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 its -deleted. Otherwise, it will simply shrink down to zero-length and sit -it 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::. + 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, a syntax table is a particular subtype of the +primitive char table type (*note Char Tables::), and each element of the +char table is an integer that encodes the syntax of the character in +question, or a cons of such an integer and a matching character (for +characters with parenthesis syntax). + + Under XEmacs 19, a syntax table is a vector of 256 elements; it +contains one entry for each of the 256 possible characters in an 8-bit +byte. Each element is an integer that encodes the syntax of the +character in question. (The matching character, if any, is embedded in +the bits of this integer.) + + Syntax tables are used only for moving across text, not for the Emacs +Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading +Lisp expressions, and these rules cannot be changed. + + Each buffer has its own major mode, and each major mode has its own +idea of the syntactic class of various characters. For example, in Lisp +mode, the character `;' begins a comment, but in C mode, it terminates +a statement. To support these variations, XEmacs makes the choice of +syntax table local to each buffer. Typically, each major mode has its +own syntax table and installs that table in each buffer that uses that +mode. Changing this table alters the syntax in all those buffers as +well as in any buffers subsequently put in that mode. Occasionally +several similar modes share one syntax table. *Note Example Major +Modes::, for an example of how to set up a syntax table. + + A syntax table can inherit the data for some characters from the +standard syntax table, while specifying other characters itself. The +"inherit" syntax class means "inherit this character's syntax from the +standard syntax table." Most major modes' syntax tables inherit the +syntax of character codes 0 through 31 and 128 through 255. This is +useful with character sets such as ISO Latin-1 that have additional +alphabetic characters in the range 128 to 255. Just changing the +standard syntax for these characters affects all major modes. + + - Function: syntax-table-p object + This function returns `t' if OBJECT is a vector of length 256 + elements. This means that the vector may be a syntax table. + However, according to this test, any vector of length 256 is + considered to be a syntax table, no matter what its contents.  -File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents - -Creating and Modifying Extents -============================== - - - Function: make-extent from to &optional object - This function makes an extent for the range [FROM, TO) in OBJECT - (a buffer or string). OBJECT 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 OBJECT 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 extent - This function returns `nil' if EXTENT is deleted, and `t' - otherwise. +File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables + +Syntax Descriptors +================== + + This section describes the syntax classes and flags that denote the +syntax of a character, and how they are represented as a "syntax +descriptor", which is a Lisp string that you pass to +`modify-syntax-entry' to specify the desired syntax. + + XEmacs defines a number of "syntax classes". Each syntax table puts +each character into one class. There is no necessary relationship +between the class of a character in one syntax table and its class in +any other table. + + Each class is designated by a mnemonic character, which serves as the +name of the class when you need to specify a class. Usually the +designator character is one that is frequently in that class; however, +its meaning as a designator is unvarying and independent of what syntax +that character currently has. + + A syntax descriptor is a Lisp string that specifies a syntax class, a +matching character (used only for the parenthesis classes) and flags. +The first character is the designator for a syntax class. The second +character is the character to match; if it is unused, put a space there. +Then come the characters for any desired flags. If no matching +character or flags are needed, one character is sufficient. + + For example, the descriptor for the character `*' in C mode is +`. 23' (i.e., punctuation, matching character slot unused, second +character of a comment-starter, first character of an comment-ender), +and the entry for `/' is `. 14' (i.e., punctuation, matching character +slot unused, first character of a comment-starter, second character of +a comment-ender). + +* Menu: + +* Syntax Class Table:: Table of syntax classes. +* Syntax Flags:: Additional flags each character can have.  -File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents +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 ` ' or `-') 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. + + - 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 `@'. -Extent Endpoints -================ + +File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors - 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. +Syntax Flags +------------ + + In addition to the classes, entries for characters in a syntax table +can include flags. There are six possible flags, represented by the +characters `1', `2', `3', `4', `b' and `p'. + + All the flags except `p' are used to describe multi-character +comment delimiters. The digit flags indicate that a character can +_also_ be part of a comment sequence, in addition to the syntactic +properties associated with its character class. The flags are +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 (`*/'). + + The flags for a character C are: + + * `1' means C is the start of a two-character comment-start sequence. + + * `2' means C is the second character of such a sequence. + + * `3' means C is the start of a two-character comment-end sequence. + + * `4' means C is the second character of such a sequence. + + * `b' means that C as a comment delimiter belongs to the alternative + "b" comment style. + + 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". + + The two comment-start sequences must begin with the same + character; only the second character may differ. Mark the second + character of the "b"-style comment-start sequence with the `b' + flag. + + A comment-end sequence (one or two characters) applies to the "b" + style if its first character has the `b' flag set; otherwise, it + applies to the "a" style. + + The appropriate comment syntax settings for C++ are as follows: + + `/' + `124b' + + `*' + `23' + + newline + `>b' + + This defines four comment-delimiting sequences: + + `/*' + This is a comment-start sequence for "a" style because the + second character, `*', does not have the `b' flag. + + `//' + This is a comment-start sequence for "b" style because the + second character, `/', does have the `b' flag. + + `*/' + This is a comment-end sequence for "a" style because the first + character, `*', does not have the `b' flag + + newline + This is a comment-end sequence for "b" style, because the + newline character has the `b' flag. + + * `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::.  -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 - 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'. - - 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: 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: 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: 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: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents +File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables -Properties of Extents -===================== +Parsing Balanced Expressions +============================ - 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 - This function returns the value of PROPERTY in EXTENT. If - PROPERTY is undefined, `nil' is returned. - - - 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 is not there at all. - -`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, + 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. - The following convenience functions are provided for setting -particular properties of an extent. + 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. - - Function: set-extent-priority extent pri - This function sets the `priority' property of EXTENT to PRI. + Scanning ignores comments if `parse-sexp-ignore-comments' is + non-`nil'. - - Function: set-extent-face extent face - This function sets the `face' property of EXTENT to FACE. + 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. - - Function: set-extent-mouse-face extent face - This function sets the `mouse-face' property of EXTENT to FACE. + If optional arg BUFFER is non-`nil', scanning occurs in that + buffer instead of in the current buffer. - - 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'. + If optional arg NOERROR is non-`nil', `scan-sexps' will return nil + instead of signalling an error. - - Function: set-extent-begin-glyph-layout extent layout - This function sets the `begin-glyph-layout' property of EXTENT to - LAYOUT. + - 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'. - - Function: set-extent-end-glyph-layout extent layout - This function sets the `end-glyph-layout' property of EXTENT to - LAYOUT. + 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. - - 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.) + You can use `forward-comment' to move forward or backward over one +comment or several comments. - - 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: 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'. - - Function: set-extent-initial-redisplay-function extent function - This function sets the `initial-redisplay-function' property of the - extent to FUNCTION. + 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: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents +File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables -Detached Extents -================ +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. - 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::. + - 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: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents +File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables -Extent Parents -============== +Syntax Table Internals +====================== - 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.) + 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::). - 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. + The low 8 bits of each element of a syntax table indicate the syntax +class. - Parent extents are used to implement the extents over the modeline. +Integer + Class - - 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. +0 + whitespace - - Function: extent-parent extent - This function return the parents (if any) of EXTENT, or `nil'. +1 + punctuation - - 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. +2 + word - - 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. +3 + symbol - -File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents +4 + open parenthesis -Duplicable Extents -================== +5 + close parenthesis + +6 + expression prefix + +7 + string quote + +8 + paired delimiter + +9 + escape + +10 + character quote + +11 + comment-start + +12 + comment-end - 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 in 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. +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: 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. 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: 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: Atomic Extents, Prev: Extents and Events, Up: Extents +File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs -Atomic Extents -============== +Setting Up Abbrev Mode +====================== - 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. + Abbrev mode is a minor mode controlled by the value of the variable +`abbrev-mode'. - To make an extent atomic, set its `atomic' property. + - 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: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top +File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs -Specifiers -********** +Abbrev Tables +============= - A specifier is an object used to keep track of a property whose value -may vary depending on the particular situation (e.g. particular buffer -displayed in a particular window) that it is used in. 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 that situation. + This section describes how to create and manipulate abbrev tables. - - Function: specifierp object - This function returns non-`nil' if OBJECT is a specifier. + - 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. -* Menu: + - Function: clear-abbrev-table table + This function undefines all the abbrevs in abbrev table TABLE, + leaving it empty. The function returns `nil'. -* Introduction to Specifiers:: Specifiers provide a clean way for - display and other properties to vary - (under user control) in a wide variety - of contexts. -* 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 Example:: 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. + - 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'. - -File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers + - 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'. -Introduction to Specifiers -========================== + 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. - Sometimes you may want the value of a property to vary depending on -the context the property is used in. A simple example of this in XEmacs -is 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. + +File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs - 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. +Defining Abbrevs +================ - A "specifier" is a generalization of this, allowing a great deal of -flexibility in controlling exactly what value a property has in which -circumstances. It is 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 + 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. - * blue for a particular buffer + - 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. - * green for all other buffers + The return value is the symbol that internally represents the new + abbrev, or `nil' if the user declines to confirm redefining an + existing abbrev. - As a more complicated example, you could specify that the foreground -of the default face be + - 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. - * forest green for all buffers displayed in a particular Emacs - window, or green if the X server doesn't recognize the color - `forest green' + The argument NAME should be a string. The argument EXPANSION + should be a string, or `nil' to undefine the abbrev. - * blue for all buffers displayed in a particular frame + 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. - * red for all other buffers displayed on a color device + The use count of the abbrev is initialized to zero. - * white for all other buffers + - 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: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers - -In-Depth Overview of a Specifier -================================ - - A specifier object encapsulates a set of "specifications", each of -which says what its value should be if a particular condition applies. -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". In specifier terminology, these conditions are -called "locales" and the values are called "instantiators". 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?". - - 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.) - - 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: 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'.