1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
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: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
55 Replacing the Text That Matched
56 -------------------------------
58 This function replaces the text matched by the last search with
61 - Function: replace-match replacement &optional fixedcase literal
63 This function replaces the text in the buffer (or in STRING) that
64 was matched by the last search. It replaces that text with
67 If you did the last search in a buffer, you should specify `nil'
68 for STRING. Then `replace-match' does the replacement by editing
69 the buffer; it leaves point at the end of the replacement text,
72 If you did the search in a string, pass the same string as STRING.
73 Then `replace-match' does the replacement by constructing and
74 returning a new string.
76 If the fourth argument STRING is a string, fifth argument
77 STRBUFFER specifies the buffer to be used for syntax-table and
78 case-table lookup and defaults to the current buffer. When STRING
79 is not a string, the buffer that the match occurred in has
80 automatically been remembered and you do not need to specify it.
82 If FIXEDCASE is non-`nil', then the case of the replacement text
83 is not changed; otherwise, the replacement text is converted to a
84 different case depending upon the capitalization of the text to be
85 replaced. If the original text is all upper case, the replacement
86 text is converted to upper case. If the first word of the
87 original text is capitalized, then the first word of the
88 replacement text is capitalized. If the original text contains
89 just one word, and that word is a capital letter, `replace-match'
90 considers this a capitalized first word rather than all upper case.
92 If `case-replace' is `nil', then case conversion is not done,
93 regardless of the value of FIXEDCASE. *Note Searching and Case::.
95 If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
96 it is, the only alterations being case changes as needed. If it
97 is `nil' (the default), then the character `\' is treated
98 specially. If a `\' appears in REPLACEMENT, then it must be part
99 of one of the following sequences:
102 `\&' stands for the entire text being replaced.
105 `\N', where N is a digit, stands for the text that matched
106 the Nth subexpression in the original regexp. Subexpressions
107 are those expressions grouped inside `\(...\)'.
110 `\\' stands for a single `\' in the replacement text.
113 File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
115 Accessing the Entire Match Data
116 -------------------------------
118 The functions `match-data' and `set-match-data' read or write the
119 entire match data, all at once.
121 - Function: match-data &optional integers reuse
122 This function returns a newly constructed list containing all the
123 information on what text the last search matched. Element zero is
124 the position of the beginning of the match for the whole
125 expression; element one is the position of the end of the match
126 for the expression. The next two elements are the positions of
127 the beginning and end of the match for the first subexpression,
128 and so on. In general, element number 2N corresponds to
129 `(match-beginning N)'; and element number 2N + 1 corresponds to
132 All the elements are markers or `nil' if matching was done on a
133 buffer, and all are integers or `nil' if matching was done on a
134 string with `string-match'. However, if the optional first
135 argument INTEGERS is non-`nil', always use integers (rather than
136 markers) to represent buffer positions.
138 If the optional second argument REUSE is a list, reuse it as part
139 of the value. If REUSE is long enough to hold all the values, and
140 if INTEGERS is non-`nil', no new lisp objects are created.
142 As always, there must be no possibility of intervening searches
143 between the call to a search function and the call to `match-data'
144 that is intended to access the match data for that search.
147 => (#<marker at 9 in foo>
148 #<marker at 17 in foo>
149 #<marker at 13 in foo>
150 #<marker at 17 in foo>)
152 - Function: set-match-data match-list
153 This function sets the match data from the elements of MATCH-LIST,
154 which should be a list that was the value of a previous call to
157 If MATCH-LIST refers to a buffer that doesn't exist, you don't get
158 an error; that sets the match data in a meaningless but harmless
161 `store-match-data' is an alias for `set-match-data'.
164 File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
166 Saving and Restoring the Match Data
167 -----------------------------------
169 When you call a function that may do a search, you may need to save
170 and restore the match data around that call, if you want to preserve the
171 match data from an earlier search for later use. Here is an example
172 that shows the problem that arises if you fail to save the match data:
174 (re-search-forward "The \\(cat \\)")
176 (foo) ; Perhaps `foo' does
179 => 61 ; Unexpected result--not 48!
181 You can save and restore the match data with `save-match-data':
183 - Special Form: save-match-data body...
184 This special form executes BODY, saving and restoring the match
187 You can use `set-match-data' together with `match-data' to imitate
188 the effect of the special form `save-match-data'. This is useful for
189 writing code that can run in Emacs 18. Here is how:
191 (let ((data (match-data)))
193 ... ; May change the original match data.
194 (set-match-data data)))
196 Emacs automatically saves and restores the match data when it runs
197 process filter functions (*note Filter Functions::) and process
198 sentinels (*note Sentinels::).
201 File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
206 By default, searches in Emacs ignore the case of the text they are
207 searching through; if you specify searching for `FOO', then `Foo' or
208 `foo' is also considered a match. Regexps, and in particular character
209 sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
211 If you do not want this feature, set the variable `case-fold-search'
212 to `nil'. Then all letters must match exactly, including case. This
213 is a buffer-local variable; altering the variable affects only the
214 current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you
215 may change the value of `default-case-fold-search', which is the
216 default value of `case-fold-search' for buffers that do not override it.
218 Note that the user-level incremental search feature handles case
219 distinctions differently. When given a lower case letter, it looks for
220 a match of either case, but when given an upper case letter, it looks
221 for an upper case letter only. But this has nothing to do with the
222 searching functions Lisp functions use.
224 - User Option: case-replace
225 This variable determines whether the replacement functions should
226 preserve case. If the variable is `nil', that means to use the
227 replacement text verbatim. A non-`nil' value means to convert the
228 case of the replacement text according to the text being replaced.
230 The function `replace-match' is where this variable actually has
231 its effect. *Note Replacing Match::.
233 - User Option: case-fold-search
234 This buffer-local variable determines whether searches should
235 ignore case. If the variable is `nil' they do not ignore case;
236 otherwise they do ignore case.
238 - Variable: default-case-fold-search
239 The value of this variable is the default value for
240 `case-fold-search' in buffers that do not override it. This is the
241 same as `(default-value 'case-fold-search)'.
244 File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching
246 Standard Regular Expressions Used in Editing
247 ============================================
249 This section describes some variables that hold regular expressions
250 used for certain purposes in editing:
252 - Variable: page-delimiter
253 This is the regexp describing line-beginnings that separate pages.
254 The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
255 matches a line that starts with a formfeed character.
257 The following two regular expressions should _not_ assume the match
258 always starts at the beginning of a line; they should not use `^' to
259 anchor the match. Most often, the paragraph commands do check for a
260 match only at the beginning of a line, which means that `^' would be
261 superfluous. When there is a nonzero left margin, they accept matches
262 that start after the left margin. In that case, a `^' would be
263 incorrect. However, a `^' is harmless in modes where a left margin is
266 - Variable: paragraph-separate
267 This is the regular expression for recognizing the beginning of a
268 line that separates paragraphs. (If you change this, you may have
269 to change `paragraph-start' also.) The default value is
270 `"[ \t\f]*$"', which matches a line that consists entirely of
271 spaces, tabs, and form feeds (after its left margin).
273 - Variable: paragraph-start
274 This is the regular expression for recognizing the beginning of a
275 line that starts _or_ separates paragraphs. The default value is
276 `"[ \t\n\f]"', which matches a line starting with a space, tab,
277 newline, or form feed (after its left margin).
279 - Variable: sentence-end
280 This is the regular expression describing the end of a sentence.
281 (All paragraph boundaries also end sentences, regardless.) The
284 "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
286 This means a period, question mark or exclamation mark, followed
287 optionally by a closing parenthetical character, followed by tabs,
290 For a detailed explanation of this regular expression, see *Note
294 File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
299 A "syntax table" specifies the syntactic textual function of each
300 character. This information is used by the parsing commands, the
301 complex movement commands, and others to determine where words, symbols,
302 and other syntactic constructs begin and end. The current syntax table
303 controls the meaning of the word motion functions (*note Word Motion::)
304 and the list motion functions (*note List Motion::) as well as the
305 functions in this chapter.
309 * Basics: Syntax Basics. Basic concepts of syntax tables.
310 * Desc: Syntax Descriptors. How characters are classified.
311 * Syntax Table Functions:: How to create, examine and alter syntax tables.
312 * Motion and Syntax:: Moving over characters with certain syntaxes.
313 * Parsing Expressions:: Parsing balanced expressions
314 using the syntax table.
315 * Standard Syntax Tables:: Syntax tables used by various major modes.
316 * Syntax Table Internals:: How syntax table information is stored.
319 File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables
321 Syntax Table Concepts
322 =====================
324 A "syntax table" provides Emacs with the information that determines
325 the syntactic use of each character in a buffer. This information is
326 used by the parsing commands, the complex movement commands, and others
327 to determine where words, symbols, and other syntactic constructs begin
328 and end. The current syntax table controls the meaning of the word
329 motion functions (*note Word Motion::) and the list motion functions
330 (*note List Motion::) as well as the functions in this chapter.
332 Under XEmacs 20, a syntax table is a particular subtype of the
333 primitive char table type (*note Char Tables::), and each element of the
334 char table is an integer that encodes the syntax of the character in
335 question, or a cons of such an integer and a matching character (for
336 characters with parenthesis syntax).
338 Under XEmacs 19, a syntax table is a vector of 256 elements; it
339 contains one entry for each of the 256 possible characters in an 8-bit
340 byte. Each element is an integer that encodes the syntax of the
341 character in question. (The matching character, if any, is embedded in
342 the bits of this integer.)
344 Syntax tables are used only for moving across text, not for the Emacs
345 Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading
346 Lisp expressions, and these rules cannot be changed.
348 Each buffer has its own major mode, and each major mode has its own
349 idea of the syntactic class of various characters. For example, in Lisp
350 mode, the character `;' begins a comment, but in C mode, it terminates
351 a statement. To support these variations, XEmacs makes the choice of
352 syntax table local to each buffer. Typically, each major mode has its
353 own syntax table and installs that table in each buffer that uses that
354 mode. Changing this table alters the syntax in all those buffers as
355 well as in any buffers subsequently put in that mode. Occasionally
356 several similar modes share one syntax table. *Note Example Major
357 Modes::, for an example of how to set up a syntax table.
359 A syntax table can inherit the data for some characters from the
360 standard syntax table, while specifying other characters itself. The
361 "inherit" syntax class means "inherit this character's syntax from the
362 standard syntax table." Most major modes' syntax tables inherit the
363 syntax of character codes 0 through 31 and 128 through 255. This is
364 useful with character sets such as ISO Latin-1 that have additional
365 alphabetic characters in the range 128 to 255. Just changing the
366 standard syntax for these characters affects all major modes.
368 - Function: syntax-table-p object
369 This function returns `t' if OBJECT is a vector of length 256
370 elements. This means that the vector may be a syntax table.
371 However, according to this test, any vector of length 256 is
372 considered to be a syntax table, no matter what its contents.
375 File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables
380 This section describes the syntax classes and flags that denote the
381 syntax of a character, and how they are represented as a "syntax
382 descriptor", which is a Lisp string that you pass to
383 `modify-syntax-entry' to specify the desired syntax.
385 XEmacs defines a number of "syntax classes". Each syntax table puts
386 each character into one class. There is no necessary relationship
387 between the class of a character in one syntax table and its class in
390 Each class is designated by a mnemonic character, which serves as the
391 name of the class when you need to specify a class. Usually the
392 designator character is one that is frequently in that class; however,
393 its meaning as a designator is unvarying and independent of what syntax
394 that character currently has.
396 A syntax descriptor is a Lisp string that specifies a syntax class, a
397 matching character (used only for the parenthesis classes) and flags.
398 The first character is the designator for a syntax class. The second
399 character is the character to match; if it is unused, put a space there.
400 Then come the characters for any desired flags. If no matching
401 character or flags are needed, one character is sufficient.
403 For example, the descriptor for the character `*' in C mode is
404 `. 23' (i.e., punctuation, matching character slot unused, second
405 character of a comment-starter, first character of an comment-ender),
406 and the entry for `/' is `. 14' (i.e., punctuation, matching character
407 slot unused, first character of a comment-starter, second character of
412 * Syntax Class Table:: Table of syntax classes.
413 * Syntax Flags:: Additional flags each character can have.
416 File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors
418 Table of Syntax Classes
419 -----------------------
421 Here is a table of syntax classes, the characters that stand for
422 them, their meanings, and examples of their use.
424 - Syntax class: whitespace character
425 "Whitespace characters" (designated with ` ' or `-') separate
426 symbols and words from each other. Typically, whitespace
427 characters have no other syntactic significance, and multiple
428 whitespace characters are syntactically equivalent to a single
429 one. Space, tab, newline and formfeed are almost always
430 classified as whitespace.
432 - Syntax class: word constituent
433 "Word constituents" (designated with `w') are parts of normal
434 English words and are typically used in variable and command names
435 in programs. All upper- and lower-case letters, and the digits,
436 are typically word constituents.
438 - Syntax class: symbol constituent
439 "Symbol constituents" (designated with `_') are the extra
440 characters that are used in variable and command names along with
441 word constituents. For example, the symbol constituents class is
442 used in Lisp mode to indicate that certain characters may be part
443 of symbol names even though they are not part of English words.
444 These characters are `$&*+-_<>'. In standard C, the only
445 non-word-constituent character that is valid in symbols is
448 - Syntax class: punctuation character
449 "Punctuation characters" (`.') are those characters that are used
450 as punctuation in English, or are used in some way in a programming
451 language to separate symbols from one another. Most programming
452 language modes, including Emacs Lisp mode, have no characters in
453 this class since the few characters that are not symbol or word
454 constituents all have other uses.
456 - Syntax class: open parenthesis character
457 - Syntax class: close parenthesis character
458 Open and close "parenthesis characters" are characters used in
459 dissimilar pairs to surround sentences or expressions. Such a
460 grouping is begun with an open parenthesis character and
461 terminated with a close. Each open parenthesis character matches
462 a particular close parenthesis character, and vice versa.
463 Normally, XEmacs indicates momentarily the matching open
464 parenthesis when you insert a close parenthesis. *Note Blinking::.
466 The class of open parentheses is designated with `(', and that of
467 close parentheses with `)'.
469 In English text, and in C code, the parenthesis pairs are `()',
470 `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and
471 vectors (`()' and `[]') are classified as parenthesis characters.
473 - Syntax class: string quote
474 "String quote characters" (designated with `"') are used in many
475 languages, including Lisp and C, to delimit string constants. The
476 same string quote character appears at the beginning and the end
477 of a string. Such quoted strings do not nest.
479 The parsing facilities of XEmacs consider a string as a single
480 token. The usual syntactic meanings of the characters in the
481 string are suppressed.
483 The Lisp modes have two string quote characters: double-quote (`"')
484 and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is
485 used in Common Lisp. C also has two string quote characters:
486 double-quote for strings, and single-quote (`'') for character
489 English text has no string quote characters because English is not
490 a programming language. Although quotation marks are used in
491 English, we do not want them to turn off the usual syntactic
492 properties of other characters in the quotation.
494 - Syntax class: escape
495 An "escape character" (designated with `\') starts an escape
496 sequence such as is used in C string and character constants. The
497 character `\' belongs to this class in both C and Lisp. (In C, it
498 is used thus only inside strings, but it turns out to cause no
499 trouble to treat it this way throughout C code.)
501 Characters in this class count as part of words if
502 `words-include-escapes' is non-`nil'. *Note Word Motion::.
504 - Syntax class: character quote
505 A "character quote character" (designated with `/') quotes the
506 following character so that it loses its normal syntactic meaning.
507 This differs from an escape character in that only the character
508 immediately following is ever affected.
510 Characters in this class count as part of words if
511 `words-include-escapes' is non-`nil'. *Note Word Motion::.
513 This class is used for backslash in TeX mode.
515 - Syntax class: paired delimiter
516 "Paired delimiter characters" (designated with `$') are like
517 string quote characters except that the syntactic properties of the
518 characters between the delimiters are not suppressed. Only TeX
519 mode uses a paired delimiter presently--the `$' that both enters
520 and leaves math mode.
522 - Syntax class: expression prefix
523 An "expression prefix operator" (designated with `'') is used for
524 syntactic operators that are part of an expression if they appear
525 next to one. These characters in Lisp include the apostrophe, `''
526 (used for quoting), the comma, `,' (used in macros), and `#' (used
527 in the read syntax for certain data types).
529 - Syntax class: comment starter
530 - Syntax class: comment ender
531 The "comment starter" and "comment ender" characters are used in
532 various languages to delimit comments. These classes are
533 designated with `<' and `>', respectively.
535 English text has no comment characters. In Lisp, the semicolon
536 (`;') starts a comment and a newline or formfeed ends one.
538 - Syntax class: inherit
539 This syntax class does not specify a syntax. It says to look in
540 the standard syntax table to find the syntax of this character.
541 The designator for this syntax code is `@'.
544 File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors
549 In addition to the classes, entries for characters in a syntax table
550 can include flags. There are six possible flags, represented by the
551 characters `1', `2', `3', `4', `b' and `p'.
553 All the flags except `p' are used to describe multi-character
554 comment delimiters. The digit flags indicate that a character can
555 _also_ be part of a comment sequence, in addition to the syntactic
556 properties associated with its character class. The flags are
557 independent of the class and each other for the sake of characters such
558 as `*' in C mode, which is a punctuation character, _and_ the second
559 character of a start-of-comment sequence (`/*'), _and_ the first
560 character of an end-of-comment sequence (`*/').
562 The flags for a character C are:
564 * `1' means C is the start of a two-character comment-start sequence.
566 * `2' means C is the second character of such a sequence.
568 * `3' means C is the start of a two-character comment-end sequence.
570 * `4' means C is the second character of such a sequence.
572 * `b' means that C as a comment delimiter belongs to the alternative
575 Emacs supports two comment styles simultaneously in any one syntax
576 table. This is for the sake of C++. Each style of comment syntax
577 has its own comment-start sequence and its own comment-end
578 sequence. Each comment must stick to one style or the other;
579 thus, if it starts with the comment-start sequence of style "b",
580 it must also end with the comment-end sequence of style "b".
582 The two comment-start sequences must begin with the same
583 character; only the second character may differ. Mark the second
584 character of the "b"-style comment-start sequence with the `b'
587 A comment-end sequence (one or two characters) applies to the "b"
588 style if its first character has the `b' flag set; otherwise, it
589 applies to the "a" style.
591 The appropriate comment syntax settings for C++ are as follows:
602 This defines four comment-delimiting sequences:
605 This is a comment-start sequence for "a" style because the
606 second character, `*', does not have the `b' flag.
609 This is a comment-start sequence for "b" style because the
610 second character, `/', does have the `b' flag.
613 This is a comment-end sequence for "a" style because the first
614 character, `*', does not have the `b' flag
617 This is a comment-end sequence for "b" style, because the
618 newline character has the `b' flag.
620 * `p' identifies an additional "prefix character" for Lisp syntax.
621 These characters are treated as whitespace when they appear between
622 expressions. When they appear within an expression, they are
623 handled according to their usual syntax codes.
625 The function `backward-prefix-chars' moves back over these
626 characters, as well as over characters whose primary syntax class
627 is prefix (`''). *Note Motion and Syntax::.
630 File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables
632 Syntax Table Functions
633 ======================
635 In this section we describe functions for creating, accessing and
636 altering syntax tables.
638 - Function: make-syntax-table &optional oldtable
639 This function creates a new syntax table. Character codes 0
640 through 31 and 128 through 255 are set up to inherit from the
641 standard syntax table. The other character codes are set up by
642 copying what the standard syntax table says about them.
644 Most major mode syntax tables are created in this way.
646 - Function: copy-syntax-table &optional syntax-table
647 This function constructs a copy of SYNTAX-TABLE and returns it.
648 If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy
649 of the current syntax table. Otherwise, an error is signaled if
650 SYNTAX-TABLE is not a syntax table.
652 - Command: modify-syntax-entry char-range syntax-descriptor &optional
654 This function sets the syntax entry for CHAR-RANGE according to
655 SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a
656 range of characters, as used with `put-char-table'. The syntax is
657 changed only for SYNTAX-TABLE, which defaults to the current
658 buffer's syntax table, and not in any other syntax table. The
659 argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a
660 string beginning with a class designator character, and optionally
661 containing a matching character and flags as well. *Note Syntax
664 This function always returns `nil'. The old syntax information in
665 the table for CHAR-RANGE is discarded.
667 An error is signaled if the first character of the syntax
668 descriptor is not one of the twelve syntax class designator
673 ;; Put the space character in class whitespace.
674 (modify-syntax-entry ?\ " ")
677 ;; Make `$' an open parenthesis character,
678 ;; with `^' as its matching close.
679 (modify-syntax-entry ?$ "(^")
682 ;; Make `^' a close parenthesis character,
683 ;; with `$' as its matching open.
684 (modify-syntax-entry ?^ ")$")
687 ;; Make `/' a punctuation character,
688 ;; the first character of a start-comment sequence,
689 ;; and the second character of an end-comment sequence.
690 ;; This is used in C mode.
691 (modify-syntax-entry ?/ ". 14")
694 - Function: char-syntax character &optional syntax-table
695 This function returns the syntax class of CHARACTER, represented
696 by its mnemonic designator character. This _only_ returns the
697 class, not any matching parenthesis or flags.
699 An error is signaled if CHARACTER is not a character.
701 The characters that correspond to various syntax codes are listed
702 in the documentation of `modify-syntax-entry'.
704 Optional second argument SYNTAX-TABLE is the syntax table to be
705 used, and defaults to the current buffer's syntax table.
707 The following examples apply to C mode. The first example shows
708 that the syntax class of space is whitespace (represented by a
709 space). The second example shows that the syntax of `/' is
710 punctuation. This does not show the fact that it is also part of
711 comment-start and -end sequences. The third example shows that
712 open parenthesis is in the class of open parentheses. This does
713 not show the fact that it has a matching character, `)'.
715 (char-to-string (char-syntax ?\ ))
718 (char-to-string (char-syntax ?/))
721 (char-to-string (char-syntax ?\())
724 - Function: set-syntax-table syntax-table &optional buffer
725 This function makes SYNTAX-TABLE the syntax table for BUFFER, which
726 defaults to the current buffer if omitted. It returns
729 - Function: syntax-table &optional buffer
730 This function returns the syntax table for BUFFER, which defaults
731 to the current buffer if omitted.
734 File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables
739 This section describes functions for moving across characters in
740 certain syntax classes. None of these functions exists in Emacs
741 version 18 or earlier.
743 - Function: skip-syntax-forward syntaxes &optional limit buffer
744 This function moves point forward across characters having syntax
745 classes mentioned in SYNTAXES. It stops when it encounters the
746 end of the buffer, or position LIMIT (if specified), or a
747 character it is not supposed to skip. Optional argument BUFFER
748 defaults to the current buffer if omitted.
750 - Function: skip-syntax-backward syntaxes &optional limit buffer
751 This function moves point backward across characters whose syntax
752 classes are mentioned in SYNTAXES. It stops when it encounters
753 the beginning of the buffer, or position LIMIT (if specified), or a
754 character it is not supposed to skip. Optional argument BUFFER
755 defaults to the current buffer if omitted.
758 - Function: backward-prefix-chars &optional buffer
759 This function moves point backward over any number of characters
760 with expression prefix syntax. This includes both characters in
761 the expression prefix syntax class, and characters with the `p'
762 flag. Optional argument BUFFER defaults to the current buffer if
766 File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
768 Parsing Balanced Expressions
769 ============================
771 Here are several functions for parsing and scanning balanced
772 expressions, also known as "sexps", in which parentheses match in
773 pairs. The syntax table controls the interpretation of characters, so
774 these functions can be used for Lisp expressions when in Lisp mode and
775 for C expressions when in C mode. *Note List Motion::, for convenient
776 higher-level functions for moving over balanced expressions.
778 - Function: parse-partial-sexp start limit &optional target-depth
779 stop-before state stop-comment buffer
780 This function parses a sexp in the current buffer starting at
781 START, not scanning past LIMIT. It stops at position LIMIT or
782 when certain criteria described below are met, and sets point to
783 the location where parsing stops. It returns a value describing
784 the status of the parse at the point where it stops.
786 If STATE is `nil', START is assumed to be at the top level of
787 parenthesis structure, such as the beginning of a function
788 definition. Alternatively, you might wish to resume parsing in the
789 middle of the structure. To do this, you must provide a STATE
790 argument that describes the initial status of parsing.
792 If the third argument TARGET-DEPTH is non-`nil', parsing stops if
793 the depth in parentheses becomes equal to TARGET-DEPTH. The depth
794 starts at 0, or at whatever is given in STATE.
796 If the fourth argument STOP-BEFORE is non-`nil', parsing stops
797 when it comes to any character that starts a sexp. If
798 STOP-COMMENT is non-`nil', parsing stops when it comes to the
801 The fifth argument STATE is an eight-element list of the same form
802 as the value of this function, described below. The return value
803 of one call may be used to initialize the state of the parse on
804 another call to `parse-partial-sexp'.
806 The result is a list of eight elements describing the final state
809 0. The depth in parentheses, counting from 0.
811 1. The character position of the start of the innermost
812 parenthetical grouping containing the stopping point; `nil'
815 2. The character position of the start of the last complete
816 subexpression terminated; `nil' if none.
818 3. Non-`nil' if inside a string. More precisely, this is the
819 character that will terminate the string.
821 4. `t' if inside a comment (of either style).
823 5. `t' if point is just after a quote character.
825 6. The minimum parenthesis depth encountered during this scan.
827 7. `t' if inside a comment of style "b".
829 Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
831 This function is most often used to compute indentation for
832 languages that have nested parentheses.
834 - Function: scan-lists from count depth &optional buffer noerror
835 This function scans forward COUNT balanced parenthetical groupings
836 from character number FROM. It returns the character position
837 where the scan stops.
839 If DEPTH is nonzero, parenthesis depth counting begins from that
840 value. The only candidates for stopping are places where the
841 depth in parentheses becomes zero; `scan-lists' counts COUNT such
842 places and then stops. Thus, a positive value for DEPTH means go
843 out DEPTH levels of parenthesis.
845 Scanning ignores comments if `parse-sexp-ignore-comments' is
848 If the scan reaches the beginning or end of the buffer (or its
849 accessible portion), and the depth is not zero, an error is
850 signaled. If the depth is zero but the count is not used up,
853 If optional arg BUFFER is non-`nil', scanning occurs in that
854 buffer instead of in the current buffer.
856 If optional arg NOERROR is non-`nil', `scan-lists' will return
857 `nil' instead of signalling an error.
859 - Function: scan-sexps from count &optional buffer noerror
860 This function scans forward COUNT sexps from character position
861 FROM. It returns the character position where the scan stops.
863 Scanning ignores comments if `parse-sexp-ignore-comments' is
866 If the scan reaches the beginning or end of (the accessible part
867 of) the buffer in the middle of a parenthetical grouping, an error
868 is signaled. If it reaches the beginning or end between groupings
869 but before count is used up, `nil' is returned.
871 If optional arg BUFFER is non-`nil', scanning occurs in that
872 buffer instead of in the current buffer.
874 If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
875 instead of signalling an error.
877 - Variable: parse-sexp-ignore-comments
878 If the value is non-`nil', then comments are treated as whitespace
879 by the functions in this section and by `forward-sexp'.
881 In older Emacs versions, this feature worked only when the comment
882 terminator is something like `*/', and appears only to end a
883 comment. In languages where newlines terminate comments, it was
884 necessary make this variable `nil', since not every newline is the
885 end of a comment. This limitation no longer exists.
887 You can use `forward-comment' to move forward or backward over one
888 comment or several comments.
890 - Function: forward-comment &optional count buffer
891 This function moves point forward across COUNT comments (backward,
892 if COUNT is negative). If it finds anything other than a comment
893 or whitespace, it stops, leaving point at the place where it
894 stopped. It also stops after satisfying COUNT. COUNT defaults to
897 Optional argument BUFFER defaults to the current buffer.
899 To move forward over all comments and whitespace following point, use
900 `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
901 to use, because the number of comments in the buffer cannot exceed that
905 File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
907 Some Standard Syntax Tables
908 ===========================
910 Most of the major modes in XEmacs have their own syntax tables. Here
913 - Function: standard-syntax-table
914 This function returns the standard syntax table, which is the
915 syntax table used in Fundamental mode.
917 - Variable: text-mode-syntax-table
918 The value of this variable is the syntax table used in Text mode.
920 - Variable: c-mode-syntax-table
921 The value of this variable is the syntax table for C-mode buffers.
923 - Variable: emacs-lisp-mode-syntax-table
924 The value of this variable is the syntax table used in Emacs Lisp
925 mode by editing commands. (It has no effect on the Lisp `read'
929 File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
931 Syntax Table Internals
932 ======================
934 Each element of a syntax table is an integer that encodes the syntax
935 of one character: the syntax class, possible matching character, and
936 flags. Lisp programs don't usually work with the elements directly; the
937 Lisp-level syntax table functions usually work with syntax descriptors
938 (*note Syntax Descriptors::).
940 The low 8 bits of each element of a syntax table indicate the syntax
988 The next 8 bits are the matching opposite parenthesis (if the
989 character has parenthesis syntax); otherwise, they are not meaningful.
990 The next 6 bits are the flags.
993 File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
995 Abbrevs And Abbrev Expansion
996 ****************************
998 An abbreviation or "abbrev" is a string of characters that may be
999 expanded to a longer string. The user can insert the abbrev string and
1000 find it replaced automatically with the expansion of the abbrev. This
1003 The set of abbrevs currently in effect is recorded in an "abbrev
1004 table". Each buffer has a local abbrev table, but normally all buffers
1005 in the same major mode share one abbrev table. There is also a global
1006 abbrev table. Normally both are used.
1008 An abbrev table is represented as an obarray containing a symbol for
1009 each abbreviation. The symbol's name is the abbreviation; its value is
1010 the expansion; its function definition is the hook function to do the
1011 expansion (*note Defining Abbrevs::); its property list cell contains
1012 the use count, the number of times the abbreviation has been expanded.
1013 Because these symbols are not interned in the usual obarray, they will
1014 never appear as the result of reading a Lisp expression; in fact,
1015 normally they are never used except by the code that handles abbrevs.
1016 Therefore, it is safe to use them in an extremely nonstandard way.
1017 *Note Creating Symbols::.
1019 For the user-level commands for abbrevs, see *Note Abbrev Mode:
1024 * Abbrev Mode:: Setting up XEmacs for abbreviation.
1025 * Tables: Abbrev Tables. Creating and working with abbrev tables.
1026 * Defining Abbrevs:: Specifying abbreviations and their expansions.
1027 * Files: Abbrev Files. Saving abbrevs in files.
1028 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
1029 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
1032 File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
1034 Setting Up Abbrev Mode
1035 ======================
1037 Abbrev mode is a minor mode controlled by the value of the variable
1040 - Variable: abbrev-mode
1041 A non-`nil' value of this variable turns on the automatic expansion
1042 of abbrevs when their abbreviations are inserted into a buffer.
1043 If the value is `nil', abbrevs may be defined, but they are not
1044 expanded automatically.
1046 This variable automatically becomes local when set in any fashion.
1048 - Variable: default-abbrev-mode
1049 This is the value of `abbrev-mode' for buffers that do not
1050 override it. This is the same as `(default-value 'abbrev-mode)'.
1053 File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
1058 This section describes how to create and manipulate abbrev tables.
1060 - Function: make-abbrev-table
1061 This function creates and returns a new, empty abbrev table--an
1062 obarray containing no symbols. It is a vector filled with zeros.
1064 - Function: clear-abbrev-table table
1065 This function undefines all the abbrevs in abbrev table TABLE,
1066 leaving it empty. The function returns `nil'.
1068 - Function: define-abbrev-table table-name definitions
1069 This function defines TABLE-NAME (a symbol) as an abbrev table
1070 name, i.e., as a variable whose value is an abbrev table. It
1071 defines abbrevs in the table according to DEFINITIONS, a list of
1072 elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The
1073 value is always `nil'.
1075 - Variable: abbrev-table-name-list
1076 This is a list of symbols whose values are abbrev tables.
1077 `define-abbrev-table' adds the new abbrev table name to this list.
1079 - Function: insert-abbrev-table-description name &optional human
1080 This function inserts before point a description of the abbrev
1081 table named NAME. The argument NAME is a symbol whose value is an
1082 abbrev table. The value is always `nil'.
1084 If HUMAN is non-`nil', the description is human-oriented.
1085 Otherwise the description is a Lisp expression--a call to
1086 `define-abbrev-table' that would define NAME exactly as it is
1090 File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
1095 These functions define an abbrev in a specified abbrev table.
1096 `define-abbrev' is the low-level basic function, while `add-abbrev' is
1097 used by commands that ask for information from the user.
1099 - Function: add-abbrev table type arg
1100 This function adds an abbreviation to abbrev table TABLE based on
1101 information from the user. The argument TYPE is a string
1102 describing in English the kind of abbrev this will be (typically,
1103 `"global"' or `"mode-specific"'); this is used in prompting the
1104 user. The argument ARG is the number of words in the expansion.
1106 The return value is the symbol that internally represents the new
1107 abbrev, or `nil' if the user declines to confirm redefining an
1110 - Function: define-abbrev table name &optional expansion hook count
1111 This function defines an abbrev in TABLE named NAME, to expand to
1112 EXPANSION, and call HOOK. The return value is an uninterned
1113 symbol that represents the abbrev inside XEmacs; its name is NAME.
1115 The argument NAME should be a string. The argument EXPANSION
1116 should be a string, or `nil' to undefine the abbrev.
1118 The argument HOOK is a function or `nil'. If HOOK is non-`nil',
1119 then it is called with no arguments after the abbrev is replaced
1120 with EXPANSION; point is located at the end of EXPANSION when HOOK
1123 The use count of the abbrev is initialized to zero.
1125 - User Option: only-global-abbrevs
1126 If this variable is non-`nil', it means that the user plans to use
1127 global abbrevs only. This tells the commands that define
1128 mode-specific abbrevs to define global ones instead. This
1129 variable does not alter the behavior of the functions in this
1130 section; it is examined by their callers.
1133 File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
1135 Saving Abbrevs in Files
1136 =======================
1138 A file of saved abbrev definitions is actually a file of Lisp code.
1139 The abbrevs are saved in the form of a Lisp program to define the same
1140 abbrev tables with the same contents. Therefore, you can load the file
1141 with `load' (*note How Programs Do Loading::). However, the function
1142 `quietly-read-abbrev-file' is provided as a more convenient interface.
1144 User-level facilities such as `save-some-buffers' can save abbrevs
1145 in a file automatically, under the control of variables described here.
1147 - User Option: abbrev-file-name
1148 This is the default file name for reading and saving abbrevs.
1150 - Function: quietly-read-abbrev-file &optional filename
1151 This function reads abbrev definitions from a file named FILENAME,
1152 previously written with `write-abbrev-file'. If FILENAME is
1153 `nil', the file specified in `abbrev-file-name' is used.
1154 `save-abbrevs' is set to `t' so that changes will be saved.
1156 This function does not display any messages. It returns `nil'.
1158 - User Option: save-abbrevs
1159 A non-`nil' value for `save-abbrev' means that XEmacs should save
1160 abbrevs when files are saved. `abbrev-file-name' specifies the
1161 file to save the abbrevs in.
1163 - Variable: abbrevs-changed
1164 This variable is set non-`nil' by defining or altering any
1165 abbrevs. This serves as a flag for various XEmacs commands to
1166 offer to save your abbrevs.
1168 - Command: write-abbrev-file filename
1169 Save all abbrev definitions, in all abbrev tables, in the file
1170 FILENAME, in the form of a Lisp program that when loaded will
1171 define the same abbrevs. This function returns `nil'.