[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45. Syntax Tables

A syntax table specifies the syntactic textual function of each character. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (see section 41.2.2 Motion by Words) and the list motion functions (see section 41.2.6 Moving over Balanced Expressions) as well as the functions in this chapter.

45.1 Syntax Table Concepts  Basic concepts of syntax tables.
45.2 Syntax Descriptors  How characters are classified.
45.3 Syntax Table Functions  How to create, examine and alter syntax tables.
45.4 Motion and Syntax  Moving over characters with certain syntaxes.
45.5 Parsing Balanced Expressions  Parsing balanced expressions using the syntax table.
45.6 Some Standard Syntax Tables  Syntax tables used by various major modes.
45.7 Syntax Table Internals  How syntax table information is stored.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.1 Syntax Table Concepts

A syntax table provides Emacs with the information that determines the syntactic use of each character in a buffer. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (see section 41.2.2 Motion by Words) and the list motion functions (see section 41.2.6 Moving over Balanced Expressions) as well as the functions in this chapter.

Under XEmacs 20 and later, a syntax table is a particular subtype of the primitive char table type (see section 10.13 The Char Table), and each element of the char table is an integer that encodes the syntax of the character in question, or a cons of such an integer and a matching character (for characters with parenthesis syntax).

Under XEmacs 19, a syntax table is a vector of 256 elements; it contains one entry for each of the 256 possible characters in an 8-bit byte. Each element is an integer that encodes the syntax of the character in question. (The matching character, if any, is embedded in the bits of this integer.)

Syntax tables are used only for moving across text, not for the Emacs Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed.

Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, XEmacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. Changing this table alters the syntax in all those buffers as well as in any buffers subsequently put in that mode. Occasionally several similar modes share one syntax table. See section 33.1.2 Major Mode Examples, for an example of how to set up a syntax table.

A syntax table can inherit the data for some characters from the standard syntax table, while specifying other characters itself. The "inherit" syntax class means "inherit this character's syntax from the standard syntax table." Most major modes' syntax tables inherit the syntax of character codes 0 through 31 and 128 through 255. This is useful with character sets such as ISO Latin-1 that have additional alphabetic characters in the range 128 to 255. Just changing the standard syntax for these characters affects all major modes.

Function: syntax-table-p object
This function returns t if object is a vector of length 256 elements. This means that the vector may be a syntax table. However, according to this test, any vector of length 256 is considered to be a syntax table, no matter what its contents.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.2 Syntax Descriptors

This section describes the syntax classes and flags that denote the syntax of a character, and how they are represented as a syntax descriptor, which is a Lisp string that you pass to modify-syntax-entry to specify the desired syntax.

XEmacs defines a number of syntax classes. Each syntax table puts each character into one class. There is no necessary relationship between the class of a character in one syntax table and its class in any other table.

Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the designator character is one that is frequently in that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has.

A syntax descriptor is a Lisp string that specifies a syntax class, a matching character (used only for the parenthesis classes) and flags. The first character is the designator for a syntax class. The second character is the character to match; if it is unused, put a space there. Then come the characters for any desired flags. If no matching character or flags are needed, one character is sufficient.

For example, the descriptor for the character `*' in C mode is `. 23' (i.e., punctuation, matching character slot unused, second character of a comment-starter, first character of an comment-ender), and the entry for `/' is `. 14' (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender).

45.2.1 Table of Syntax Classes  Table of syntax classes.
45.2.2 Syntax Flags  Additional flags each character can have.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.2.1 Table of Syntax Classes

Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use.

Syntax class: whitespace character
Whitespace characters (designated with `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic significance, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are almost always classified as whitespace. (The designator ` ' is accepted for backwards compatibility with older versions of XEmacs, but is deprecated. It is invalid in GNU Emacs.)

Syntax class: word constituent
Word constituents (designated with `w') are parts of normal English words and are typically used in variable and command names in programs. All upper- and lower-case letters, and the digits, are typically word constituents.

Syntax class: symbol constituent
Symbol constituents (designated with `_') are the extra characters that are used in variable and command names along with word constituents. For example, the symbol constituents class is used in Lisp mode to indicate that certain characters may be part of symbol names even though they are not part of English words. These characters are `$&*+-_<>'. In standard C, the only non-word-constituent character that is valid in symbols is underscore (`_').

Syntax class: punctuation character
Punctuation characters (`.') are those characters that are used as punctuation in English, or are used in some way in a programming language to separate symbols from one another. Most programming language modes, including Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses.

Syntax class: open parenthesis character
Syntax class: close parenthesis character
Open and close parenthesis characters are characters used in dissimilar pairs to surround sentences or expressions. Such a grouping is begun with an open parenthesis character and terminated with a close. Each open parenthesis character matches a particular close parenthesis character, and vice versa. Normally, XEmacs indicates momentarily the matching open parenthesis when you insert a close parenthesis. See section 52.9 Blinking Parentheses.

The class of open parentheses is designated with `(', and that of close parentheses with `)'.

In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters.

Syntax class: string quote
String quote characters (designated with `"') are used in many languages, including Lisp and C, to delimit string constants. The same string quote character appears at the beginning and the end of a string. Such quoted strings do not nest.

The parsing facilities of XEmacs consider a string as a single token. The usual syntactic meanings of the characters in the string are suppressed.

The Lisp modes have two string quote characters: double-quote (`"') and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and single-quote (`'') for character constants.

English text has no string quote characters because English is not a programming language. Although quotation marks are used in English, we do not want them to turn off the usual syntactic properties of other characters in the quotation.

Syntax class: escape
An escape character (designated with `\') starts an escape sequence such as is used in C string and character constants. The character `\' belongs to this class in both C and Lisp. (In C, it is used thus only inside strings, but it turns out to cause no trouble to treat it this way throughout C code.)

Characters in this class count as part of words if words-include-escapes is non-nil. See section 41.2.2 Motion by Words.

Syntax class: character quote
A character quote character (designated with `/') quotes the following character so that it loses its normal syntactic meaning. This differs from an escape character in that only the character immediately following is ever affected.

Characters in this class count as part of words if words-include-escapes is non-nil. See section 41.2.2 Motion by Words.

This class is used for backslash in TeX mode.

Syntax class: paired delimiter
Paired delimiter characters (designated with `$') are like string quote characters except that the syntactic properties of the characters between the delimiters are not suppressed. Only TeX mode uses a paired delimiter presently--the `$' that both enters and leaves math mode.

Syntax class: expression prefix
An expression prefix operator (designated with `'') is used for syntactic operators that are part of an expression if they appear next to one. These characters in Lisp include the apostrophe, `'' (used for quoting), the comma, `,' (used in macros), and `#' (used in the read syntax for certain data types).

Syntax class: comment starter
Syntax class: comment ender
The comment starter and comment ender characters are used in various languages to delimit comments. These classes are designated with `<' and `>', respectively.

English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one.

Syntax class: inherit
This syntax class does not specify a syntax. It says to look in the standard syntax table to find the syntax of this character. The designator for this syntax code is `@'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.2.2 Syntax Flags

In addition to the classes, entries for characters in a syntax table can include flags. There are eleven possible flags, represented by the digits `1'--`8', and the lowercase letters `a', `b', and `p'.

All the flags except `p' are used to describe comment delimiters. The digit flags indicate that a character can also be part of a multi-character comment sequence, in addition to the syntactic properties associated with its character class. The flags must be independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, and the second character of a start-of-comment sequence (`/*'), and the first character of an end-of-comment sequence (`*/').

Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with the comment-start sequence of style "b", it must also end with the comment-end sequence of style "b".

As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary comment-start sequences and two arbitrary comment-end sequences. (Thus the need for 8 flags.) GNU Emacs restricts the comment-start sequences to start with the same character, XEmacs does not. This means that for two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses the digit flags `5'--`8'.

A one character comment-end sequence applies to the "b" style if its first character has the `b' flag set; otherwise, it applies to the "a" style. The `a' flag is optional. These flags have no effect on non-comment characters; two-character styles are determined by the digit flags.

The flags for a character c are:

Lisp (as you would expect) has a simple comment syntax.

`;'
`<'
newline
`>'

Note that no flags are used. This defines two comment-delimiting sequences:

`;'
This is a single-character comment-start sequence because the syntax class is `<'.

newline
This is a single character comment-end sequence because the syntax class is `>' and the `b' flag is not set.

C++ (again, as you would expect) has a baroque, overrich, and excessively complex comment syntax.

`/'
`1456'
`*'
`23'
newline
`>b'

Note that the "b" style mixes one-character and two-character sequences. The table above defines four comment-delimiting sequences:

`/*'
This is a comment-start sequence for "a" style because the `1' flag is set on `/' and the `2' flag is set on `*'.

`//'
This is a comment-start sequence for "b" style because both the `5' and the `6' flags are set on `/'.

`*/'
This is a comment-end sequence for "a" style because the `3' flag is set on `*' and the `4' flag is set on `/'.

newline
This is a comment-end sequence for "b" style, because the newline character has the `b' flag.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.3 Syntax Table Functions

In this section we describe functions for creating, accessing and altering syntax tables.

Function: make-syntax-table &optional oldtable
This function creates a new syntax table. Character codes 0 through 31 and 128 through 255 are set up to inherit from the standard syntax table. The other character codes are set up by copying what the standard syntax table says about them.

Most major mode syntax tables are created in this way.

Function: copy-syntax-table &optional syntax-table
This function constructs a copy of syntax-table and returns it. If syntax-table is not supplied (or is nil), it returns a copy of the current syntax table. Otherwise, an error is signaled if syntax-table is not a syntax table.

Command: modify-syntax-entry char-range syntax-descriptor &optional syntax-table
This function sets the syntax entry for char-range according to syntax-descriptor. char-range is either a single character or a range of characters, as used with put-char-table. The syntax is changed only for syntax-table, which defaults to the current buffer's syntax table, and not in any other syntax table. The argument syntax-descriptor specifies the desired syntax; this is a string beginning with a class designator character, and optionally containing a matching character and flags as well. See section 45.2 Syntax Descriptors.

This function always returns nil. The old syntax information in the table for char-range is discarded.

An error is signaled if the first character of the syntax descriptor is not one of the twelve syntax class designator characters.

 
Examples:

;; Put the space character in class whitespace.
(modify-syntax-entry ?\  " ")
     => nil

;; Make `$' an open parenthesis character,
;;   with `^' as its matching close.
(modify-syntax-entry ?$ "(^")
     => nil

;; Make `^' a close parenthesis character,
;;   with `$' as its matching open.
(modify-syntax-entry ?^ ")$")
     => nil

;; Make `/' a punctuation character,
;;   the first character of a start-comment sequence,
;;   and the second character of an end-comment sequence.
;;   This is used in C mode.
(modify-syntax-entry ?/ ". 14")
     => nil

Function: char-syntax character &optional syntax-table
This function returns the syntax class of character, represented by its mnemonic designator character. This only returns the class, not any matching parenthesis or flags.

An error is signaled if character is not a character.

The characters that correspond to various syntax codes are listed in the documentation of modify-syntax-entry.

Optional second argument syntax-table is the syntax table to be used, and defaults to the current buffer's syntax table.

The following examples apply to C mode. The first example shows that the syntax class of space is whitespace (represented by a space). The second example shows that the syntax of `/' is punctuation. This does not show the fact that it is also part of comment-start and -end sequences. The third example shows that open parenthesis is in the class of open parentheses. This does not show the fact that it has a matching character, `)'.

 
(char-to-string (char-syntax ?\ ))
     => " "

(char-to-string (char-syntax ?/))
     => "."

(char-to-string (char-syntax ?\())
     => "("

Function: set-syntax-table syntax-table &optional buffer
This function makes syntax-table the syntax table for buffer, which defaults to the current buffer if omitted. It returns syntax-table.

Function: syntax-table &optional buffer
This function returns the syntax table for buffer, which defaults to the current buffer if omitted.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.4 Motion and Syntax

This section describes functions for moving across characters in certain syntax classes. None of these functions exists in Emacs version 18 or earlier.

Function: skip-syntax-forward syntaxes &optional limit buffer
This function moves point forward across characters having syntax classes mentioned in syntaxes. It stops when it encounters the end of the buffer, or position limit (if specified), or a character it is not supposed to skip. Optional argument buffer defaults to the current buffer if omitted.

Function: skip-syntax-backward syntaxes &optional limit buffer
This function moves point backward across characters whose syntax classes are mentioned in syntaxes. It stops when it encounters the beginning of the buffer, or position limit (if specified), or a character it is not supposed to skip. Optional argument buffer defaults to the current buffer if omitted.

Function: backward-prefix-chars &optional buffer
This function moves point backward over any number of characters with expression prefix syntax. This includes both characters in the expression prefix syntax class, and characters with the `p' flag. Optional argument buffer defaults to the current buffer if omitted.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.5 Parsing Balanced Expressions

Here are several functions for parsing and scanning balanced expressions, also known as sexps, in which parentheses match in pairs. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. See section 41.2.6 Moving over Balanced Expressions, for convenient higher-level functions for moving over balanced expressions.

Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment buffer
This function parses a sexp in the current buffer starting at start, not scanning past limit. It stops at position limit or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a value describing the status of the parse at the point where it stops.

If state is nil, start is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a state argument that describes the initial status of parsing.

If the third argument target-depth is non-nil, parsing stops if the depth in parentheses becomes equal to target-depth. The depth starts at 0, or at whatever is given in state.

If the fourth argument stop-before is non-nil, parsing stops when it comes to any character that starts a sexp. If stop-comment is non-nil, parsing stops when it comes to the start of a comment.

The fifth argument state is an eight-element list of the same form as the value of this function, described below. The return value of one call may be used to initialize the state of the parse on another call to parse-partial-sexp.

The result is a list of eight elements describing the final state of the parse:

  1. The depth in parentheses, counting from 0.

  2. The character position of the start of the innermost parenthetical grouping containing the stopping point; nil if none.

  3. The character position of the start of the last complete subexpression terminated; nil if none.

  4. Non-nil if inside a string. More precisely, this is the character that will terminate the string.

  5. t if inside a comment (of either style).

  6. t if point is just after a quote character.

  7. The minimum parenthesis depth encountered during this scan.

  8. t if inside a comment of style "b".

Elements 0, 3, 4, 5 and 7 are significant in the argument state.

This function is most often used to compute indentation for languages that have nested parentheses.

Function: scan-lists from count depth &optional buffer noerror
This function scans forward count balanced parenthetical groupings from character number from. It returns the character position where the scan stops.

If depth is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; scan-lists counts count such places and then stops. Thus, a positive value for depth means go out depth levels of parenthesis.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, nil is returned.

If optional arg buffer is non-nil, scanning occurs in that buffer instead of in the current buffer.

If optional arg noerror is non-nil, scan-lists will return nil instead of signalling an error.

Function: scan-sexps from count &optional buffer noerror
This function scans forward count sexps from character position from. It returns the character position where the scan stops.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of (the accessible part of) the buffer in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, nil is returned.

If optional arg buffer is non-nil, scanning occurs in that buffer instead of in the current buffer.

If optional arg noerror is non-nil, scan-sexps will return nil instead of signalling an error.

Variable: parse-sexp-ignore-comments
If the value is non-nil, then comments are treated as whitespace by the functions in this section and by forward-sexp.

In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable nil, since not every newline is the end of a comment. This limitation no longer exists.

You can use forward-comment to move forward or backward over one comment or several comments.

Function: forward-comment &optional count buffer
This function moves point forward across count comments (backward, if count is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying count. count defaults to 1.

Optional argument buffer defaults to the current buffer.

To move forward over all comments and whitespace following point, use (forward-comment (buffer-size)). (buffer-size) is a good argument to use, because the number of comments in the buffer cannot exceed that many.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.6 Some Standard Syntax Tables

Most of the major modes in XEmacs have their own syntax tables. Here are several of them:

Function: standard-syntax-table
This function returns the standard syntax table, which is the syntax table used in Fundamental mode.

Variable: text-mode-syntax-table
The value of this variable is the syntax table used in Text mode.

Variable: c-mode-syntax-table
The value of this variable is the syntax table for C-mode buffers.

Variable: emacs-lisp-mode-syntax-table
The value of this variable is the syntax table used in Emacs Lisp mode by editing commands. (It has no effect on the Lisp read function.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

45.7 Syntax Table Internals

Each element of a syntax table is an integer that encodes the syntax of one character: the syntax class, possible matching character, and flags. Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (see section 45.2 Syntax Descriptors).

The low 8 bits of each element of a syntax table indicate the syntax class.

Integer
Class
0
whitespace
1
punctuation
2
word
3
symbol
4
open parenthesis
5
close parenthesis
6
expression prefix
7
string quote
8
paired delimiter
9
escape
10
character quote
11
comment-start
12
comment-end
13
inherit

The next 8 bits are the matching opposite parenthesis (if the character has parenthesis syntax); otherwise, they are not meaningful. The next 6 bits are the flags.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on August, 3 2012 using texi2html