1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
55 Accessing the Entire Match Data
56 -------------------------------
58 The functions `match-data' and `set-match-data' read or write the
59 entire match data, all at once.
61 - Function: match-data
62 This function returns a newly constructed list containing all the
63 information on what text the last search matched. Element zero is
64 the position of the beginning of the match for the whole
65 expression; element one is the position of the end of the match
66 for the expression. The next two elements are the positions of
67 the beginning and end of the match for the first subexpression,
68 and so on. In general, element number 2N corresponds to
69 `(match-beginning N)'; and element number 2N + 1 corresponds to
72 All the elements are markers or `nil' if matching was done on a
73 buffer, and all are integers or `nil' if matching was done on a
74 string with `string-match'. (In Emacs 18 and earlier versions,
75 markers were used even for matching on a string, except in the case
78 As always, there must be no possibility of intervening searches
79 between the call to a search function and the call to `match-data'
80 that is intended to access the match data for that search.
83 => (#<marker at 9 in foo>
84 #<marker at 17 in foo>
85 #<marker at 13 in foo>
86 #<marker at 17 in foo>)
88 - Function: set-match-data MATCH-LIST
89 This function sets the match data from the elements of MATCH-LIST,
90 which should be a list that was the value of a previous call to
93 If MATCH-LIST refers to a buffer that doesn't exist, you don't get
94 an error; that sets the match data in a meaningless but harmless
97 `store-match-data' is an alias for `set-match-data'.
100 File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
102 Saving and Restoring the Match Data
103 -----------------------------------
105 When you call a function that may do a search, you may need to save
106 and restore the match data around that call, if you want to preserve the
107 match data from an earlier search for later use. Here is an example
108 that shows the problem that arises if you fail to save the match data:
110 (re-search-forward "The \\(cat \\)")
112 (foo) ; Perhaps `foo' does
115 => 61 ; Unexpected result--not 48!
117 You can save and restore the match data with `save-match-data':
119 - Macro: save-match-data BODY...
120 This special form executes BODY, saving and restoring the match
123 You can use `set-match-data' together with `match-data' to imitate
124 the effect of the special form `save-match-data'. This is useful for
125 writing code that can run in Emacs 18. Here is how:
127 (let ((data (match-data)))
129 ... ; May change the original match data.
130 (set-match-data data)))
132 Emacs automatically saves and restores the match data when it runs
133 process filter functions (*note Filter Functions::.) and process
134 sentinels (*note Sentinels::.).
137 File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
142 By default, searches in Emacs ignore the case of the text they are
143 searching through; if you specify searching for `FOO', then `Foo' or
144 `foo' is also considered a match. Regexps, and in particular character
145 sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
147 If you do not want this feature, set the variable `case-fold-search'
148 to `nil'. Then all letters must match exactly, including case. This
149 is a buffer-local variable; altering the variable affects only the
150 current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you
151 may change the value of `default-case-fold-search', which is the
152 default value of `case-fold-search' for buffers that do not override it.
154 Note that the user-level incremental search feature handles case
155 distinctions differently. When given a lower case letter, it looks for
156 a match of either case, but when given an upper case letter, it looks
157 for an upper case letter only. But this has nothing to do with the
158 searching functions Lisp functions use.
160 - User Option: case-replace
161 This variable determines whether the replacement functions should
162 preserve case. If the variable is `nil', that means to use the
163 replacement text verbatim. A non-`nil' value means to convert the
164 case of the replacement text according to the text being replaced.
166 The function `replace-match' is where this variable actually has
167 its effect. *Note Replacing Match::.
169 - User Option: case-fold-search
170 This buffer-local variable determines whether searches should
171 ignore case. If the variable is `nil' they do not ignore case;
172 otherwise they do ignore case.
174 - Variable: default-case-fold-search
175 The value of this variable is the default value for
176 `case-fold-search' in buffers that do not override it. This is the
177 same as `(default-value 'case-fold-search)'.
180 File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching
182 Standard Regular Expressions Used in Editing
183 ============================================
185 This section describes some variables that hold regular expressions
186 used for certain purposes in editing:
188 - Variable: page-delimiter
189 This is the regexp describing line-beginnings that separate pages.
190 The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
191 matches a line that starts with a formfeed character.
193 The following two regular expressions should *not* assume the match
194 always starts at the beginning of a line; they should not use `^' to
195 anchor the match. Most often, the paragraph commands do check for a
196 match only at the beginning of a line, which means that `^' would be
197 superfluous. When there is a nonzero left margin, they accept matches
198 that start after the left margin. In that case, a `^' would be
199 incorrect. However, a `^' is harmless in modes where a left margin is
202 - Variable: paragraph-separate
203 This is the regular expression for recognizing the beginning of a
204 line that separates paragraphs. (If you change this, you may have
205 to change `paragraph-start' also.) The default value is
206 `"[ \t\f]*$"', which matches a line that consists entirely of
207 spaces, tabs, and form feeds (after its left margin).
209 - Variable: paragraph-start
210 This is the regular expression for recognizing the beginning of a
211 line that starts *or* separates paragraphs. The default value is
212 `"[ \t\n\f]"', which matches a line starting with a space, tab,
213 newline, or form feed (after its left margin).
215 - Variable: sentence-end
216 This is the regular expression describing the end of a sentence.
217 (All paragraph boundaries also end sentences, regardless.) The
220 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
222 This means a period, question mark or exclamation mark, followed
223 optionally by a closing parenthetical character, followed by tabs,
226 For a detailed explanation of this regular expression, see *Note
230 File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
235 A "syntax table" specifies the syntactic textual function of each
236 character. This information is used by the parsing commands, the
237 complex movement commands, and others to determine where words, symbols,
238 and other syntactic constructs begin and end. The current syntax table
239 controls the meaning of the word motion functions (*note Word Motion::.)
240 and the list motion functions (*note List Motion::.) as well as the
241 functions in this chapter.
245 * Basics: Syntax Basics. Basic concepts of syntax tables.
246 * Desc: Syntax Descriptors. How characters are classified.
247 * Syntax Table Functions:: How to create, examine and alter syntax tables.
248 * Motion and Syntax:: Moving over characters with certain syntaxes.
249 * Parsing Expressions:: Parsing balanced expressions
250 using the syntax table.
251 * Standard Syntax Tables:: Syntax tables used by various major modes.
252 * Syntax Table Internals:: How syntax table information is stored.
255 File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables
257 Syntax Table Concepts
258 =====================
260 A "syntax table" provides Emacs with the information that determines
261 the syntactic use of each character in a buffer. This information is
262 used by the parsing commands, the complex movement commands, and others
263 to determine where words, symbols, and other syntactic constructs begin
264 and end. The current syntax table controls the meaning of the word
265 motion functions (*note Word Motion::.) and the list motion functions
266 (*note List Motion::.) as well as the functions in this chapter.
268 Under XEmacs 20, a syntax table is a particular subtype of the
269 primitive char table type (*note Char Tables::.), and each element of
270 the char table is an integer that encodes the syntax of the character in
271 question, or a cons of such an integer and a matching character (for
272 characters with parenthesis syntax).
274 Under XEmacs 19, a syntax table is a vector of 256 elements; it
275 contains one entry for each of the 256 possible characters in an 8-bit
276 byte. Each element is an integer that encodes the syntax of the
277 character in question. (The matching character, if any, is embedded in
278 the bits of this integer.)
280 Syntax tables are used only for moving across text, not for the Emacs
281 Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading
282 Lisp expressions, and these rules cannot be changed.
284 Each buffer has its own major mode, and each major mode has its own
285 idea of the syntactic class of various characters. For example, in Lisp
286 mode, the character `;' begins a comment, but in C mode, it terminates
287 a statement. To support these variations, XEmacs makes the choice of
288 syntax table local to each buffer. Typically, each major mode has its
289 own syntax table and installs that table in each buffer that uses that
290 mode. Changing this table alters the syntax in all those buffers as
291 well as in any buffers subsequently put in that mode. Occasionally
292 several similar modes share one syntax table. *Note Example Major
293 Modes::, for an example of how to set up a syntax table.
295 A syntax table can inherit the data for some characters from the
296 standard syntax table, while specifying other characters itself. The
297 "inherit" syntax class means "inherit this character's syntax from the
298 standard syntax table." Most major modes' syntax tables inherit the
299 syntax of character codes 0 through 31 and 128 through 255. This is
300 useful with character sets such as ISO Latin-1 that have additional
301 alphabetic characters in the range 128 to 255. Just changing the
302 standard syntax for these characters affects all major modes.
304 - Function: syntax-table-p OBJECT
305 This function returns `t' if OBJECT is a vector of length 256
306 elements. This means that the vector may be a syntax table.
307 However, according to this test, any vector of length 256 is
308 considered to be a syntax table, no matter what its contents.
311 File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables
316 This section describes the syntax classes and flags that denote the
317 syntax of a character, and how they are represented as a "syntax
318 descriptor", which is a Lisp string that you pass to
319 `modify-syntax-entry' to specify the desired syntax.
321 XEmacs defines a number of "syntax classes". Each syntax table puts
322 each character into one class. There is no necessary relationship
323 between the class of a character in one syntax table and its class in
326 Each class is designated by a mnemonic character, which serves as the
327 name of the class when you need to specify a class. Usually the
328 designator character is one that is frequently in that class; however,
329 its meaning as a designator is unvarying and independent of what syntax
330 that character currently has.
332 A syntax descriptor is a Lisp string that specifies a syntax class, a
333 matching character (used only for the parenthesis classes) and flags.
334 The first character is the designator for a syntax class. The second
335 character is the character to match; if it is unused, put a space there.
336 Then come the characters for any desired flags. If no matching
337 character or flags are needed, one character is sufficient.
339 For example, the descriptor for the character `*' in C mode is
340 `. 23' (i.e., punctuation, matching character slot unused, second
341 character of a comment-starter, first character of an comment-ender),
342 and the entry for `/' is `. 14' (i.e., punctuation, matching character
343 slot unused, first character of a comment-starter, second character of
348 * Syntax Class Table:: Table of syntax classes.
349 * Syntax Flags:: Additional flags each character can have.
352 File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors
354 Table of Syntax Classes
355 -----------------------
357 Here is a table of syntax classes, the characters that stand for
358 them, their meanings, and examples of their use.
360 - Syntax class: whitespace character
361 "Whitespace characters" (designated with ` ' or `-') separate
362 symbols and words from each other. Typically, whitespace
363 characters have no other syntactic significance, and multiple
364 whitespace characters are syntactically equivalent to a single
365 one. Space, tab, newline and formfeed are almost always
366 classified as whitespace.
368 - Syntax class: word constituent
369 "Word constituents" (designated with `w') are parts of normal
370 English words and are typically used in variable and command names
371 in programs. All upper- and lower-case letters, and the digits,
372 are typically word constituents.
374 - Syntax class: symbol constituent
375 "Symbol constituents" (designated with `_') are the extra
376 characters that are used in variable and command names along with
377 word constituents. For example, the symbol constituents class is
378 used in Lisp mode to indicate that certain characters may be part
379 of symbol names even though they are not part of English words.
380 These characters are `$&*+-_<>'. In standard C, the only
381 non-word-constituent character that is valid in symbols is
384 - Syntax class: punctuation character
385 "Punctuation characters" (`.') are those characters that are used
386 as punctuation in English, or are used in some way in a programming
387 language to separate symbols from one another. Most programming
388 language modes, including Emacs Lisp mode, have no characters in
389 this class since the few characters that are not symbol or word
390 constituents all have other uses.
392 - Syntax class: open parenthesis character
393 - Syntax class: close parenthesis character
394 Open and close "parenthesis characters" are characters used in
395 dissimilar pairs to surround sentences or expressions. Such a
396 grouping is begun with an open parenthesis character and
397 terminated with a close. Each open parenthesis character matches
398 a particular close parenthesis character, and vice versa.
399 Normally, XEmacs indicates momentarily the matching open
400 parenthesis when you insert a close parenthesis. *Note Blinking::.
402 The class of open parentheses is designated with `(', and that of
403 close parentheses with `)'.
405 In English text, and in C code, the parenthesis pairs are `()',
406 `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and
407 vectors (`()' and `[]') are classified as parenthesis characters.
409 - Syntax class: string quote
410 "String quote characters" (designated with `"') are used in many
411 languages, including Lisp and C, to delimit string constants. The
412 same string quote character appears at the beginning and the end
413 of a string. Such quoted strings do not nest.
415 The parsing facilities of XEmacs consider a string as a single
416 token. The usual syntactic meanings of the characters in the
417 string are suppressed.
419 The Lisp modes have two string quote characters: double-quote (`"')
420 and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is
421 used in Common Lisp. C also has two string quote characters:
422 double-quote for strings, and single-quote (`'') for character
425 English text has no string quote characters because English is not
426 a programming language. Although quotation marks are used in
427 English, we do not want them to turn off the usual syntactic
428 properties of other characters in the quotation.
430 - Syntax class: escape
431 An "escape character" (designated with `\') starts an escape
432 sequence such as is used in C string and character constants. The
433 character `\' belongs to this class in both C and Lisp. (In C, it
434 is used thus only inside strings, but it turns out to cause no
435 trouble to treat it this way throughout C code.)
437 Characters in this class count as part of words if
438 `words-include-escapes' is non-`nil'. *Note Word Motion::.
440 - Syntax class: character quote
441 A "character quote character" (designated with `/') quotes the
442 following character so that it loses its normal syntactic meaning.
443 This differs from an escape character in that only the character
444 immediately following is ever affected.
446 Characters in this class count as part of words if
447 `words-include-escapes' is non-`nil'. *Note Word Motion::.
449 This class is used for backslash in TeX mode.
451 - Syntax class: paired delimiter
452 "Paired delimiter characters" (designated with `$') are like
453 string quote characters except that the syntactic properties of the
454 characters between the delimiters are not suppressed. Only TeX
455 mode uses a paired delimiter presently--the `$' that both enters
456 and leaves math mode.
458 - Syntax class: expression prefix
459 An "expression prefix operator" (designated with `'') is used for
460 syntactic operators that are part of an expression if they appear
461 next to one. These characters in Lisp include the apostrophe, `''
462 (used for quoting), the comma, `,' (used in macros), and `#' (used
463 in the read syntax for certain data types).
465 - Syntax class: comment starter
466 - Syntax class: comment ender
467 The "comment starter" and "comment ender" characters are used in
468 various languages to delimit comments. These classes are
469 designated with `<' and `>', respectively.
471 English text has no comment characters. In Lisp, the semicolon
472 (`;') starts a comment and a newline or formfeed ends one.
474 - Syntax class: inherit
475 This syntax class does not specify a syntax. It says to look in
476 the standard syntax table to find the syntax of this character.
477 The designator for this syntax code is `@'.
480 File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors
485 In addition to the classes, entries for characters in a syntax table
486 can include flags. There are six possible flags, represented by the
487 characters `1', `2', `3', `4', `b' and `p'.
489 All the flags except `p' are used to describe multi-character
490 comment delimiters. The digit flags indicate that a character can
491 *also* be part of a comment sequence, in addition to the syntactic
492 properties associated with its character class. The flags are
493 independent of the class and each other for the sake of characters such
494 as `*' in C mode, which is a punctuation character, *and* the second
495 character of a start-of-comment sequence (`/*'), *and* the first
496 character of an end-of-comment sequence (`*/').
498 The flags for a character C are:
500 * `1' means C is the start of a two-character comment-start sequence.
502 * `2' means C is the second character of such a sequence.
504 * `3' means C is the start of a two-character comment-end sequence.
506 * `4' means C is the second character of such a sequence.
508 * `b' means that C as a comment delimiter belongs to the alternative
511 Emacs supports two comment styles simultaneously in any one syntax
512 table. This is for the sake of C++. Each style of comment syntax
513 has its own comment-start sequence and its own comment-end
514 sequence. Each comment must stick to one style or the other;
515 thus, if it starts with the comment-start sequence of style "b",
516 it must also end with the comment-end sequence of style "b".
518 The two comment-start sequences must begin with the same
519 character; only the second character may differ. Mark the second
520 character of the "b"-style comment-start sequence with the `b'
523 A comment-end sequence (one or two characters) applies to the "b"
524 style if its first character has the `b' flag set; otherwise, it
525 applies to the "a" style.
527 The appropriate comment syntax settings for C++ are as follows:
538 This defines four comment-delimiting sequences:
541 This is a comment-start sequence for "a" style because the
542 second character, `*', does not have the `b' flag.
545 This is a comment-start sequence for "b" style because the
546 second character, `/', does have the `b' flag.
549 This is a comment-end sequence for "a" style because the first
550 character, `*', does not have the `b' flag
553 This is a comment-end sequence for "b" style, because the
554 newline character has the `b' flag.
556 * `p' identifies an additional "prefix character" for Lisp syntax.
557 These characters are treated as whitespace when they appear between
558 expressions. When they appear within an expression, they are
559 handled according to their usual syntax codes.
561 The function `backward-prefix-chars' moves back over these
562 characters, as well as over characters whose primary syntax class
563 is prefix (`''). *Note Motion and Syntax::.
566 File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables
568 Syntax Table Functions
569 ======================
571 In this section we describe functions for creating, accessing and
572 altering syntax tables.
574 - Function: make-syntax-table &optional TABLE
575 This function creates a new syntax table. Character codes 0
576 through 31 and 128 through 255 are set up to inherit from the
577 standard syntax table. The other character codes are set up by
578 copying what the standard syntax table says about them.
580 Most major mode syntax tables are created in this way.
582 - Function: copy-syntax-table &optional TABLE
583 This function constructs a copy of TABLE and returns it. If TABLE
584 is not supplied (or is `nil'), it returns a copy of the current
585 syntax table. Otherwise, an error is signaled if TABLE is not a
588 - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE
589 This function sets the syntax entry for CHAR according to
590 SYNTAX-DESCRIPTOR. The syntax is changed only for TABLE, which
591 defaults to the current buffer's syntax table, and not in any
592 other syntax table. The argument SYNTAX-DESCRIPTOR specifies the
593 desired syntax; this is a string beginning with a class designator
594 character, and optionally containing a matching character and
595 flags as well. *Note Syntax Descriptors::.
597 This function always returns `nil'. The old syntax information in
598 the table for this character is discarded.
600 An error is signaled if the first character of the syntax
601 descriptor is not one of the twelve syntax class designator
602 characters. An error is also signaled if CHAR is not a character.
606 ;; Put the space character in class whitespace.
607 (modify-syntax-entry ?\ " ")
610 ;; Make `$' an open parenthesis character,
611 ;; with `^' as its matching close.
612 (modify-syntax-entry ?$ "(^")
615 ;; Make `^' a close parenthesis character,
616 ;; with `$' as its matching open.
617 (modify-syntax-entry ?^ ")$")
620 ;; Make `/' a punctuation character,
621 ;; the first character of a start-comment sequence,
622 ;; and the second character of an end-comment sequence.
623 ;; This is used in C mode.
624 (modify-syntax-entry ?/ ". 14")
627 - Function: char-syntax CHARACTER
628 This function returns the syntax class of CHARACTER, represented
629 by its mnemonic designator character. This *only* returns the
630 class, not any matching parenthesis or flags.
632 An error is signaled if CHAR is not a character.
634 The following examples apply to C mode. The first example shows
635 that the syntax class of space is whitespace (represented by a
636 space). The second example shows that the syntax of `/' is
637 punctuation. This does not show the fact that it is also part of
638 comment-start and -end sequences. The third example shows that
639 open parenthesis is in the class of open parentheses. This does
640 not show the fact that it has a matching character, `)'.
642 (char-to-string (char-syntax ?\ ))
645 (char-to-string (char-syntax ?/))
648 (char-to-string (char-syntax ?\())
651 - Function: set-syntax-table TABLE &optional BUFFER
652 This function makes TABLE the syntax table for BUFFER, which
653 defaults to the current buffer if omitted. It returns TABLE.
655 - Function: syntax-table &optional BUFFER
656 This function returns the syntax table for BUFFER, which defaults
657 to the current buffer if omitted.
660 File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables
665 This section describes functions for moving across characters in
666 certain syntax classes. None of these functions exists in Emacs
667 version 18 or earlier.
669 - Function: skip-syntax-forward SYNTAXES &optional LIMIT BUFFER
670 This function moves point forward across characters having syntax
671 classes mentioned in SYNTAXES. It stops when it encounters the
672 end of the buffer, or position LIMIT (if specified), or a
673 character it is not supposed to skip. Optional argument BUFFER
674 defaults to the current buffer if omitted.
676 - Function: skip-syntax-backward SYNTAXES &optional LIMIT BUFFER
677 This function moves point backward across characters whose syntax
678 classes are mentioned in SYNTAXES. It stops when it encounters
679 the beginning of the buffer, or position LIMIT (if specified), or a
680 character it is not supposed to skip. Optional argument BUFFER
681 defaults to the current buffer if omitted.
684 - Function: backward-prefix-chars &optional BUFFER
685 This function moves point backward over any number of characters
686 with expression prefix syntax. This includes both characters in
687 the expression prefix syntax class, and characters with the `p'
688 flag. Optional argument BUFFER defaults to the current buffer if
692 File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
694 Parsing Balanced Expressions
695 ============================
697 Here are several functions for parsing and scanning balanced
698 expressions, also known as "sexps", in which parentheses match in
699 pairs. The syntax table controls the interpretation of characters, so
700 these functions can be used for Lisp expressions when in Lisp mode and
701 for C expressions when in C mode. *Note List Motion::, for convenient
702 higher-level functions for moving over balanced expressions.
704 - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
705 STOP-BEFORE STATE STOP-COMMENT BUFFER
706 This function parses a sexp in the current buffer starting at
707 START, not scanning past LIMIT. It stops at position LIMIT or
708 when certain criteria described below are met, and sets point to
709 the location where parsing stops. It returns a value describing
710 the status of the parse at the point where it stops.
712 If STATE is `nil', START is assumed to be at the top level of
713 parenthesis structure, such as the beginning of a function
714 definition. Alternatively, you might wish to resume parsing in the
715 middle of the structure. To do this, you must provide a STATE
716 argument that describes the initial status of parsing.
718 If the third argument TARGET-DEPTH is non-`nil', parsing stops if
719 the depth in parentheses becomes equal to TARGET-DEPTH. The depth
720 starts at 0, or at whatever is given in STATE.
722 If the fourth argument STOP-BEFORE is non-`nil', parsing stops
723 when it comes to any character that starts a sexp. If
724 STOP-COMMENT is non-`nil', parsing stops when it comes to the
727 The fifth argument STATE is an eight-element list of the same form
728 as the value of this function, described below. The return value
729 of one call may be used to initialize the state of the parse on
730 another call to `parse-partial-sexp'.
732 The result is a list of eight elements describing the final state
735 0. The depth in parentheses, counting from 0.
737 1. The character position of the start of the innermost
738 parenthetical grouping containing the stopping point; `nil'
741 2. The character position of the start of the last complete
742 subexpression terminated; `nil' if none.
744 3. Non-`nil' if inside a string. More precisely, this is the
745 character that will terminate the string.
747 4. `t' if inside a comment (of either style).
749 5. `t' if point is just after a quote character.
751 6. The minimum parenthesis depth encountered during this scan.
753 7. `t' if inside a comment of style "b".
755 Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
757 This function is most often used to compute indentation for
758 languages that have nested parentheses.
760 - Function: scan-lists FROM COUNT DEPTH &optional BUFFER NOERROR
761 This function scans forward COUNT balanced parenthetical groupings
762 from character number FROM. It returns the character position
763 where the scan stops.
765 If DEPTH is nonzero, parenthesis depth counting begins from that
766 value. The only candidates for stopping are places where the
767 depth in parentheses becomes zero; `scan-lists' counts COUNT such
768 places and then stops. Thus, a positive value for DEPTH means go
769 out DEPTH levels of parenthesis.
771 Scanning ignores comments if `parse-sexp-ignore-comments' is
774 If the scan reaches the beginning or end of the buffer (or its
775 accessible portion), and the depth is not zero, an error is
776 signaled. If the depth is zero but the count is not used up,
779 If optional arg BUFFER is non-`nil', scanning occurs in that
780 buffer instead of in the current buffer.
782 If optional arg NOERROR is non-`nil', `scan-lists' will return
783 `nil' instead of signalling an error.
785 - Function: scan-sexps FROM COUNT &optional BUFFER NOERROR
786 This function scans forward COUNT sexps from character position
787 FROM. It returns the character position where the scan stops.
789 Scanning ignores comments if `parse-sexp-ignore-comments' is
792 If the scan reaches the beginning or end of (the accessible part
793 of) the buffer in the middle of a parenthetical grouping, an error
794 is signaled. If it reaches the beginning or end between groupings
795 but before count is used up, `nil' is returned.
797 If optional arg BUFFER is non-`nil', scanning occurs in that
798 buffer instead of in the current buffer.
800 If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
801 instead of signalling an error.
803 - Variable: parse-sexp-ignore-comments
804 If the value is non-`nil', then comments are treated as whitespace
805 by the functions in this section and by `forward-sexp'.
807 In older Emacs versions, this feature worked only when the comment
808 terminator is something like `*/', and appears only to end a
809 comment. In languages where newlines terminate comments, it was
810 necessary make this variable `nil', since not every newline is the
811 end of a comment. This limitation no longer exists.
813 You can use `forward-comment' to move forward or backward over one
814 comment or several comments.
816 - Function: forward-comment COUNT &optional BUFFER
817 This function moves point forward across COUNT comments (backward,
818 if COUNT is negative). If it finds anything other than a comment
819 or whitespace, it stops, leaving point at the place where it
820 stopped. It also stops after satisfying COUNT.
822 Optional argument BUFFER defaults to the current buffer.
824 To move forward over all comments and whitespace following point, use
825 `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
826 to use, because the number of comments in the buffer cannot exceed that
830 File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
832 Some Standard Syntax Tables
833 ===========================
835 Most of the major modes in XEmacs have their own syntax tables. Here
838 - Function: standard-syntax-table
839 This function returns the standard syntax table, which is the
840 syntax table used in Fundamental mode.
842 - Variable: text-mode-syntax-table
843 The value of this variable is the syntax table used in Text mode.
845 - Variable: c-mode-syntax-table
846 The value of this variable is the syntax table for C-mode buffers.
848 - Variable: emacs-lisp-mode-syntax-table
849 The value of this variable is the syntax table used in Emacs Lisp
850 mode by editing commands. (It has no effect on the Lisp `read'
854 File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
856 Syntax Table Internals
857 ======================
859 Each element of a syntax table is an integer that encodes the syntax
860 of one character: the syntax class, possible matching character, and
861 flags. Lisp programs don't usually work with the elements directly; the
862 Lisp-level syntax table functions usually work with syntax descriptors
863 (*note Syntax Descriptors::.).
865 The low 8 bits of each element of a syntax table indicate the syntax
913 The next 8 bits are the matching opposite parenthesis (if the
914 character has parenthesis syntax); otherwise, they are not meaningful.
915 The next 6 bits are the flags.
918 File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
920 Abbrevs And Abbrev Expansion
921 ****************************
923 An abbreviation or "abbrev" is a string of characters that may be
924 expanded to a longer string. The user can insert the abbrev string and
925 find it replaced automatically with the expansion of the abbrev. This
928 The set of abbrevs currently in effect is recorded in an "abbrev
929 table". Each buffer has a local abbrev table, but normally all buffers
930 in the same major mode share one abbrev table. There is also a global
931 abbrev table. Normally both are used.
933 An abbrev table is represented as an obarray containing a symbol for
934 each abbreviation. The symbol's name is the abbreviation; its value is
935 the expansion; its function definition is the hook function to do the
936 expansion (*note Defining Abbrevs::.); its property list cell contains
937 the use count, the number of times the abbreviation has been expanded.
938 Because these symbols are not interned in the usual obarray, they will
939 never appear as the result of reading a Lisp expression; in fact,
940 normally they are never used except by the code that handles abbrevs.
941 Therefore, it is safe to use them in an extremely nonstandard way.
942 *Note Creating Symbols::.
944 For the user-level commands for abbrevs, see *Note Abbrev Mode:
949 * Abbrev Mode:: Setting up XEmacs for abbreviation.
950 * Tables: Abbrev Tables. Creating and working with abbrev tables.
951 * Defining Abbrevs:: Specifying abbreviations and their expansions.
952 * Files: Abbrev Files. Saving abbrevs in files.
953 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
954 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
957 File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
959 Setting Up Abbrev Mode
960 ======================
962 Abbrev mode is a minor mode controlled by the value of the variable
965 - Variable: abbrev-mode
966 A non-`nil' value of this variable turns on the automatic expansion
967 of abbrevs when their abbreviations are inserted into a buffer.
968 If the value is `nil', abbrevs may be defined, but they are not
969 expanded automatically.
971 This variable automatically becomes local when set in any fashion.
973 - Variable: default-abbrev-mode
974 This is the value of `abbrev-mode' for buffers that do not
975 override it. This is the same as `(default-value 'abbrev-mode)'.
978 File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
983 This section describes how to create and manipulate abbrev tables.
985 - Function: make-abbrev-table
986 This function creates and returns a new, empty abbrev table--an
987 obarray containing no symbols. It is a vector filled with zeros.
989 - Function: clear-abbrev-table TABLE
990 This function undefines all the abbrevs in abbrev table TABLE,
991 leaving it empty. The function returns `nil'.
993 - Function: define-abbrev-table TABNAME DEFINITIONS
994 This function defines TABNAME (a symbol) as an abbrev table name,
995 i.e., as a variable whose value is an abbrev table. It defines
996 abbrevs in the table according to DEFINITIONS, a list of elements
997 of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
1000 - Variable: abbrev-table-name-list
1001 This is a list of symbols whose values are abbrev tables.
1002 `define-abbrev-table' adds the new abbrev table name to this list.
1004 - Function: insert-abbrev-table-description NAME &optional HUMAN
1005 This function inserts before point a description of the abbrev
1006 table named NAME. The argument NAME is a symbol whose value is an
1007 abbrev table. The value is always `nil'.
1009 If HUMAN is non-`nil', the description is human-oriented.
1010 Otherwise the description is a Lisp expression--a call to
1011 `define-abbrev-table' that would define NAME exactly as it is
1015 File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
1020 These functions define an abbrev in a specified abbrev table.
1021 `define-abbrev' is the low-level basic function, while `add-abbrev' is
1022 used by commands that ask for information from the user.
1024 - Function: add-abbrev TABLE TYPE ARG
1025 This function adds an abbreviation to abbrev table TABLE based on
1026 information from the user. The argument TYPE is a string
1027 describing in English the kind of abbrev this will be (typically,
1028 `"global"' or `"mode-specific"'); this is used in prompting the
1029 user. The argument ARG is the number of words in the expansion.
1031 The return value is the symbol that internally represents the new
1032 abbrev, or `nil' if the user declines to confirm redefining an
1035 - Function: define-abbrev TABLE NAME EXPANSION HOOK
1036 This function defines an abbrev in TABLE named NAME, to expand to
1037 EXPANSION, and call HOOK. The return value is an uninterned
1038 symbol that represents the abbrev inside XEmacs; its name is NAME.
1040 The argument NAME should be a string. The argument EXPANSION
1041 should be a string, or `nil' to undefine the abbrev.
1043 The argument HOOK is a function or `nil'. If HOOK is non-`nil',
1044 then it is called with no arguments after the abbrev is replaced
1045 with EXPANSION; point is located at the end of EXPANSION when HOOK
1048 The use count of the abbrev is initialized to zero.
1050 - User Option: only-global-abbrevs
1051 If this variable is non-`nil', it means that the user plans to use
1052 global abbrevs only. This tells the commands that define
1053 mode-specific abbrevs to define global ones instead. This
1054 variable does not alter the behavior of the functions in this
1055 section; it is examined by their callers.
1058 File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
1060 Saving Abbrevs in Files
1061 =======================
1063 A file of saved abbrev definitions is actually a file of Lisp code.
1064 The abbrevs are saved in the form of a Lisp program to define the same
1065 abbrev tables with the same contents. Therefore, you can load the file
1066 with `load' (*note How Programs Do Loading::.). However, the function
1067 `quietly-read-abbrev-file' is provided as a more convenient interface.
1069 User-level facilities such as `save-some-buffers' can save abbrevs
1070 in a file automatically, under the control of variables described here.
1072 - User Option: abbrev-file-name
1073 This is the default file name for reading and saving abbrevs.
1075 - Function: quietly-read-abbrev-file FILENAME
1076 This function reads abbrev definitions from a file named FILENAME,
1077 previously written with `write-abbrev-file'. If FILENAME is
1078 `nil', the file specified in `abbrev-file-name' is used.
1079 `save-abbrevs' is set to `t' so that changes will be saved.
1081 This function does not display any messages. It returns `nil'.
1083 - User Option: save-abbrevs
1084 A non-`nil' value for `save-abbrev' means that XEmacs should save
1085 abbrevs when files are saved. `abbrev-file-name' specifies the
1086 file to save the abbrevs in.
1088 - Variable: abbrevs-changed
1089 This variable is set non-`nil' by defining or altering any
1090 abbrevs. This serves as a flag for various XEmacs commands to
1091 offer to save your abbrevs.
1093 - Command: write-abbrev-file FILENAME
1094 Save all abbrev definitions, in all abbrev tables, in the file
1095 FILENAME, in the form of a Lisp program that when loaded will
1096 define the same abbrevs. This function returns `nil'.
1099 File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
1101 Looking Up and Expanding Abbreviations
1102 ======================================
1104 Abbrevs are usually expanded by commands for interactive use,
1105 including `self-insert-command'. This section describes the
1106 subroutines used in writing such functions, as well as the variables
1107 they use for communication.
1109 - Function: abbrev-symbol ABBREV &optional TABLE
1110 This function returns the symbol representing the abbrev named
1111 ABBREV. The value returned is `nil' if that abbrev is not
1112 defined. The optional second argument TABLE is the abbrev table
1113 to look it up in. If TABLE is `nil', this function tries first
1114 the current buffer's local abbrev table, and second the global
1117 - Function: abbrev-expansion ABBREV &optional TABLE
1118 This function returns the string that ABBREV would expand into (as
1119 defined by the abbrev tables used for the current buffer). The
1120 optional argument TABLE specifies the abbrev table to use, as in
1123 - Command: expand-abbrev
1124 This command expands the abbrev before point, if any. If point
1125 does not follow an abbrev, this command does nothing. The command
1126 returns `t' if it did expansion, `nil' otherwise.
1128 - Command: abbrev-prefix-mark &optional ARG
1129 Mark current point as the beginning of an abbrev. The next call to
1130 `expand-abbrev' will use the text from here to point (where it is
1131 then) as the abbrev to expand, rather than using the previous word
1134 - User Option: abbrev-all-caps
1135 When this is set non-`nil', an abbrev entered entirely in upper
1136 case is expanded using all upper case. Otherwise, an abbrev
1137 entered entirely in upper case is expanded by capitalizing each
1138 word of the expansion.
1140 - Variable: abbrev-start-location
1141 This is the buffer position for `expand-abbrev' to use as the start
1142 of the next abbrev to be expanded. (`nil' means use the word
1143 before point instead.) `abbrev-start-location' is set to `nil'
1144 each time `expand-abbrev' is called. This variable is also set by
1145 `abbrev-prefix-mark'.
1147 - Variable: abbrev-start-location-buffer
1148 The value of this variable is the buffer for which
1149 `abbrev-start-location' has been set. Trying to expand an abbrev
1150 in any other buffer clears `abbrev-start-location'. This variable
1151 is set by `abbrev-prefix-mark'.
1153 - Variable: last-abbrev
1154 This is the `abbrev-symbol' of the last abbrev expanded. This
1155 information is left by `expand-abbrev' for the sake of the
1156 `unexpand-abbrev' command.
1158 - Variable: last-abbrev-location
1159 This is the location of the last abbrev expanded. This contains
1160 information left by `expand-abbrev' for the sake of the
1161 `unexpand-abbrev' command.
1163 - Variable: last-abbrev-text
1164 This is the exact expansion text of the last abbrev expanded,
1165 after case conversion (if any). Its value is `nil' if the abbrev
1166 has already been unexpanded. This contains information left by
1167 `expand-abbrev' for the sake of the `unexpand-abbrev' command.
1169 - Variable: pre-abbrev-expand-hook
1170 This is a normal hook whose functions are executed, in sequence,
1171 just before any expansion of an abbrev. *Note Hooks::. Since it
1172 is a normal hook, the hook functions receive no arguments.
1173 However, they can find the abbrev to be expanded by looking in the
1174 buffer before point.
1176 The following sample code shows a simple use of
1177 `pre-abbrev-expand-hook'. If the user terminates an abbrev with a
1178 punctuation character, the hook function asks for confirmation. Thus,
1179 this hook allows the user to decide whether to expand the abbrev, and
1180 aborts expansion if it is not confirmed.
1182 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
1184 ;; This is the function invoked by `pre-abbrev-expand-hook'.
1186 ;; If the user terminated the abbrev with a space, the function does
1187 ;; nothing (that is, it returns so that the abbrev can expand). If the
1188 ;; user entered some other character, this function asks whether
1189 ;; expansion should continue.
1191 ;; If the user answers the prompt with `y', the function returns
1192 ;; `nil' (because of the `not' function), but that is
1193 ;; acceptable; the return value has no effect on expansion.
1195 (defun query-if-not-space ()
1196 (if (/= ?\ (preceding-char))
1197 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
1198 (error "Not expanding this abbrev"))))
1201 File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
1203 Standard Abbrev Tables
1204 ======================
1206 Here we list the variables that hold the abbrev tables for the
1207 preloaded major modes of XEmacs.
1209 - Variable: global-abbrev-table
1210 This is the abbrev table for mode-independent abbrevs. The abbrevs
1211 defined in it apply to all buffers. Each buffer may also have a
1212 local abbrev table, whose abbrev definitions take precedence over
1213 those in the global table.
1215 - Variable: local-abbrev-table
1216 The value of this buffer-local variable is the (mode-specific)
1217 abbreviation table of the current buffer.
1219 - Variable: fundamental-mode-abbrev-table
1220 This is the local abbrev table used in Fundamental mode; in other
1221 words, it is the local abbrev table in all buffers in Fundamental
1224 - Variable: text-mode-abbrev-table
1225 This is the local abbrev table used in Text mode.
1227 - Variable: c-mode-abbrev-table
1228 This is the local abbrev table used in C mode.
1230 - Variable: lisp-mode-abbrev-table
1231 This is the local abbrev table used in Lisp mode and Emacs Lisp