A syntax table specifies the syntactic textual function of each character. This information is used by the parsing functions, 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 Motion by Words) and the list motion functions (see section Moving over Balanced Expressions), as well as the functions in this chapter.
A syntax table is a char-table (see section Char-Tables). The element at index c describes the character with code c. The element's value should be a list that encodes the syntax of the character in question.
Syntax tables are used only for moving across text, not for the Emacs Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. (Some Lisp systems provide ways to redefine the read syntax, but we decided to leave this feature out of Emacs Lisp for simplicity.)
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, Emacs 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 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." Just changing the standard syntax for a characters affects all syntax tables which inherit from it.
t
if object is a syntax table.
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 syntax you
want.
The syntax table specifies a syntax class for each character. 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 syntax 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).
Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use.
The class of open parentheses is designated by `(', and that of close parentheses by `)'.
In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In Emacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters.
The parsing facilities of Emacs 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 Emacs 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.
Characters in this class count as part of words if
words-include-escapes
is non-nil
. See
section Motion by Words.
Characters in this class count as part of words if
words-include-escapes
is non-nil
. See
section Motion by Words.
This class is used for backslash in TeX mode.
English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one.
This syntax class is primarily meant for use with the
syntax-table
text property (see section Syntax Properties). You can mark any
range of characters as forming a comment, by giving the first and
last characters of the range syntax-table
properties
identifying them as generic comment delimiters.
This syntax class is primarily meant for use with the
syntax-table
text property (see section Syntax Properties). You can mark any
range of characters as forming a string constant, by giving the
first and last characters of the range syntax-table
properties identifying them as generic string delimiters.
In addition to the classes, entries for characters in a syntax table can specify flags. There are six possible flags, represented by the characters `1', `2', `3', `4', `b' and `p'.
All the flags except `p' are used to describe multi-character comment delimiters. The digit flags indicate that a character can also be part of a comment sequence, in addition to the syntactic properties associated with its character class. The flags are independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, and the second character of a start-of-comment sequence (`/*'), and the first character of an end-of-comment sequence (`*/').
Here is a table of the possible flags for a character c, and what they mean:
backward-prefix-chars
moves back over
these characters, as well as over characters whose primary syntax
class is prefix (`''). See section Motion and Syntax.
In this section we describe functions for creating, accessing and altering syntax tables.
Most major mode syntax tables are created in this way.
nil
), it returns a copy of the current
syntax table. Otherwise, an error is signaled if table
is not a syntax table.
This function always returns nil
. The old syntax
information in the table for this character is discarded.
An error is signaled if the first character of the syntax descriptor is not one of the twelve syntax class designator characters. An error is also signaled if char is not a character.
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
An error is signaled if char is not a character.
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, `)'.
(string (char-syntax ?\ )) => " " (string (char-syntax ?/)) => "." (string (char-syntax ?\()) => "("
We use string
to make it easier to see the
character returned by char-syntax
.
When the syntax table is not flexible enough to specify the
syntax of a language, you can use syntax-table
text
properties to override the syntax table for specific character
occurrences in the buffer. See section Text Properties.
The valid values of syntax-table
text property
are:
(syntax-code .
matching-char)
nil
nil
, the character's syntax is
determined from the current syntax table in the usual way.
nil
, the syntax
scanning functions pay attention to syntax text properties.
Otherwise they use only the current syntax table.
This section describes functions for moving across characters that have certain syntax classes.
The return value indicates the distance traveled. It is an integer that is zero or less.
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 Moving over Balanced Expressions, for convenient higher-level functions for moving over balanced expressions.
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. If stop-comment is the symbol
syntax-table
, parsing stops after the start of a
comment or a string, or the end of a comment or a string, whichever
comes first.
The fifth argument
state is a nine-element list of the same form as the
value of this function, described below. (It is OK to omit the last
element of the nine.) 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 nine elements describing the final state of the parse:
nil
if none.
nil
if none.
nil
if
inside a string. More precisely, this is the character that will
terminate the string, or t
if a generic string
delimiter character should terminate it.
t
if inside a
comment (of either style).
t
if point is
just after a quote character.
nil
for a comment
of style "a", t
for a comment of style "b", and
syntax-table
for a comment that should be ended by a
generic comment delimiter character.
nil
.
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.
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.
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 while 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.
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.
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.
Most of the major modes in Emacs have their own syntax tables. Here are several of them:
read
function.)
Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (see section Syntax Descriptors). Nonetheless, here we document the internal format.
Each element of a syntax table is a cons cell of the form
(syntax-code . matching-char)
.
The CAR, syntax-code, is an integer that encodes the
syntax class, and any flags. The CDR, matching-char, is
non-nil
if a character to match was specified.
This table gives the value of syntax-code which corresponds to each syntactic type.
IntegerClassIntegerClassInteger Class0 whitespace 5 close parenthesis 10 character quote 1 punctuation 6 expression prefix 11 comment-start 2 word 7 string quote 12 comment-end 3 symbol 8 paired delimiter 13 inherit 4 open parenthesis 9 escape 14 comment-fence 15 string-fenceFor example, the usual syntax value for `(' is
(4 . 41)
. (41 is the character code for
`)'.)
The flags are encoded in higher order bits, starting 16 bits from the least significant bit. This table gives the power of two which corresponds to each syntax flag.
PrefixFlagPrefixFlagPrefixFlag `1'(lsh 1 16)
`3'(lsh 1
18)
`p'(lsh 1
20)
`2'(lsh 1
17)
`4'(lsh 1
19)
`b'(lsh 1 21)
Categories provide an alternate way of classifying characters syntactically. You can define several categories as needed, then independently assign each character to one or more categories. Unlike syntax classes, categories are not mutually exclusive; it is normal for one character to belong to several categories.
Each buffer has a category table which records which categories are defined and also which characters belong to each category. Each category table defines its own categories, but normally these are initialized by copying from the standard categories table, so that the standard categories are available in all modes.
Each category has a name, which is an ASCII printing character
in the range ` ' to `~'. You specify the
name of a category when you define it with
define-category
.
The category table is actually a char-table (see section Char-Tables). The element of the
category table at index c is a category set---a
bool-vector--that indicates which categories character c
belongs to. In this category set, if the element at index
cat is t
, that means category
cat is a member of the set, and that character
c belongs to category cat.
The new category is defined for category table table, which defaults to the current buffer's category table.
(category-docstring ?a) => "ASCII" (category-docstring ?l) => "Latin"
nil
.
t
if object is a category table, otherwise
nil
.
nil
), it returns a copy of the current
category table. Otherwise, an error is signaled if table
is not a category table.
t
for each of those categories, and
nil
for all other categories. (make-category-set "al") => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
char-category-set
does not
allocate storage, because it returns the same bool-vector that
exists in the category table. (char-category-set ?a) => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
(category-set-mnemonics (char-category-set ?a)) => "al"
Normally, it modifies the category set by adding
category to it. But if reset is
non-nil
, then it deletes category
instead.