1
0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-24 10:38:38 +00:00
emacs/lispref/syntax.texi

1008 lines
36 KiB
Plaintext
Raw Normal View History

1994-03-28 05:41:05 +00:00
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
1998-02-28 01:53:53 +00:00
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
1994-03-28 05:41:05 +00:00
@c See the file elisp.texi for copying conditions.
@setfilename ../info/syntax
@node Syntax Tables, Abbrevs, Searching and Matching, Top
@chapter Syntax Tables
@cindex parsing
@cindex syntax table
@cindex text parsing
A @dfn{syntax table} specifies the syntactic textual function of each
1998-05-19 03:45:57 +00:00
character. This information is used by the @dfn{parsing functions}, the
1994-03-28 05:41:05 +00:00
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 (@pxref{Word Motion})
1998-02-28 01:53:53 +00:00
and the list motion functions (@pxref{List Motion}), as well as the
1994-03-28 05:41:05 +00:00
functions in this chapter.
@menu
* Basics: Syntax Basics. Basic concepts of syntax tables.
* Desc: Syntax Descriptors. How characters are classified.
* Syntax Table Functions:: How to create, examine and alter syntax tables.
1998-02-28 01:53:53 +00:00
* Syntax Properties:: Overriding syntax with text properties.
1994-03-28 05:41:05 +00:00
* Motion and Syntax:: Moving over characters with certain syntaxes.
* Parsing Expressions:: Parsing balanced expressions
using the syntax table.
* Standard Syntax Tables:: Syntax tables used by various major modes.
* Syntax Table Internals:: How syntax table information is stored.
1998-02-28 01:53:53 +00:00
* Categories:: Another way of classifying character syntax.
1994-03-28 05:41:05 +00:00
@end menu
@node Syntax Basics
@section Syntax Table Concepts
@ifinfo
A @dfn{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 (@pxref{Word Motion}) and the
list motion functions (@pxref{List Motion}) as well as the functions in
this chapter.
@end ifinfo
1998-04-20 17:43:57 +00:00
A syntax table is a char-table (@pxref{Char-Tables}). The element at
index @var{c} describes the character with code @var{c}. The element's
value should be a list that encodes the syntax of the character in
question.
1994-03-28 05:41:05 +00:00
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
1998-04-20 17:43:57 +00:00
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.)
1994-03-28 05:41:05 +00:00
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 @samp{;} 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
1994-08-07 00:25:52 +00:00
that uses that mode. Changing this table alters the syntax in all
1994-03-28 05:41:05 +00:00
those buffers as well as in any buffers subsequently put in that mode.
Occasionally several similar modes share one syntax table.
@xref{Example Major Modes}, for an example of how to set up a syntax
table.
A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself. The
``inherit'' syntax class means ``inherit this character's syntax from
1998-02-28 01:53:53 +00:00
the standard syntax table.'' Just changing the standard syntax for a
1999-09-17 06:59:04 +00:00
character affects all syntax tables that inherit from it.
1994-03-28 05:41:05 +00:00
@defun syntax-table-p object
1998-02-28 01:53:53 +00:00
This function returns @code{t} if @var{object} is a syntax table.
1994-03-28 05:41:05 +00:00
@end defun
@node Syntax Descriptors
@section Syntax Descriptors
@cindex syntax classes
This section describes the syntax classes and flags that denote the
syntax of a character, and how they are represented as a @dfn{syntax
descriptor}, which is a Lisp string that you pass to
1998-04-20 17:43:57 +00:00
@code{modify-syntax-entry} to specify the syntax you want.
1994-03-28 05:41:05 +00:00
1998-04-20 17:43:57 +00:00
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.
1994-03-28 05:41:05 +00:00
1994-08-07 00:25:52 +00:00
Each class is designated by a mnemonic character, which serves as the
1994-03-28 05:41:05 +00:00
name of the class when you need to specify a class. Usually the
1999-09-17 06:59:04 +00:00
designator character is one that is often assigned that class; however,
1994-08-07 00:25:52 +00:00
its meaning as a designator is unvarying and independent of what syntax
1999-09-17 06:59:04 +00:00
that character currently has. Thus, @samp{\} as a designator character
always gives ``escape character'' syntax, regardless of what syntax
@samp{\} currently has.
1994-03-28 05:41:05 +00:00
@cindex syntax descriptor
1994-08-07 00:25:52 +00:00
A syntax descriptor is a Lisp string that specifies a syntax class, a
1994-03-28 05:41:05 +00:00
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.
1998-02-28 01:53:53 +00:00
For example, the syntax descriptor for the character @samp{*} in C
mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
1999-09-17 06:59:04 +00:00
unused, second character of a comment-starter, first character of a
1994-03-28 05:41:05 +00:00
comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
punctuation, matching character slot unused, first character of a
comment-starter, second character of a comment-ender).
@menu
* Syntax Class Table:: Table of syntax classes.
* Syntax Flags:: Additional flags each character can have.
@end menu
@node Syntax Class Table
@subsection Table of Syntax Classes
1994-08-07 00:25:52 +00:00
Here is a table of syntax classes, the characters that stand for them,
1994-03-28 05:41:05 +00:00
their meanings, and examples of their use.
@deffn {Syntax class} @w{whitespace character}
1998-02-28 01:53:53 +00:00
@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
1994-03-28 05:41:05 +00:00
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,
1998-04-20 17:43:57 +00:00
newline and formfeed are classified as whitespace in almost all major
modes.
1994-03-28 05:41:05 +00:00
@end deffn
@deffn {Syntax class} @w{word constituent}
1998-02-28 01:53:53 +00:00
@dfn{Word constituents} (designated by @samp{w}) are parts of normal
1994-03-28 05:41:05 +00:00
English words and are typically used in variable and command names in
1994-08-07 00:25:52 +00:00
programs. All upper- and lower-case letters, and the digits, are typically
1994-03-28 05:41:05 +00:00
word constituents.
@end deffn
@deffn {Syntax class} @w{symbol constituent}
1998-02-28 01:53:53 +00:00
@dfn{Symbol constituents} (designated by @samp{_}) are the extra
1994-03-28 05:41:05 +00:00
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 @samp{$&*+-_<>}. In standard C, the only non-word-constituent
character that is valid in symbols is underscore (@samp{_}).
@end deffn
@deffn {Syntax class} @w{punctuation character}
1998-02-28 01:53:53 +00:00
@dfn{Punctuation characters} (designated by @samp{.}) 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.
1994-03-28 05:41:05 +00:00
@end deffn
@deffn {Syntax class} @w{open parenthesis character}
@deffnx {Syntax class} @w{close parenthesis character}
@cindex parenthesis syntax
Open and close @dfn{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, Emacs indicates momentarily the
matching open parenthesis when you insert a close parenthesis.
@xref{Blinking}.
1998-02-28 01:53:53 +00:00
The class of open parentheses is designated by @samp{(}, and that of
close parentheses by @samp{)}.
1994-03-28 05:41:05 +00:00
In English text, and in C code, the parenthesis pairs are @samp{()},
@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and
vectors (@samp{()} and @samp{[]}) are classified as parenthesis
characters.
@end deffn
@deffn {Syntax class} @w{string quote}
1998-02-28 01:53:53 +00:00
@dfn{String quote characters} (designated by @samp{"}) are used in
1994-03-28 05:41:05 +00:00
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 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 (@samp{"})
and vertical bar (@samp{|}). @samp{|} 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 (@samp{'}) 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.
@end deffn
@deffn {Syntax class} @w{escape}
1998-02-28 01:53:53 +00:00
An @dfn{escape character} (designated by @samp{\}) starts an escape
1994-03-28 05:41:05 +00:00
sequence such as is used in C string and character constants. The
character @samp{\} 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
@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
@end deffn
@deffn {Syntax class} @w{character quote}
1998-02-28 01:53:53 +00:00
A @dfn{character quote character} (designated by @samp{/}) quotes the
1994-03-28 05:41:05 +00:00
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
@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
This class is used for backslash in @TeX{} mode.
1994-03-28 05:41:05 +00:00
@end deffn
@deffn {Syntax class} @w{paired delimiter}
1998-02-28 01:53:53 +00:00
@dfn{Paired delimiter characters} (designated by @samp{$}) are like
1994-03-28 05:41:05 +00:00
string quote characters except that the syntactic properties of the
characters between the delimiters are not suppressed. Only @TeX{} mode
1994-08-07 00:25:52 +00:00
uses a paired delimiter presently---the @samp{$} that both enters and
leaves math mode.
1994-03-28 05:41:05 +00:00
@end deffn
@deffn {Syntax class} @w{expression prefix}
1998-02-28 01:53:53 +00:00
An @dfn{expression prefix operator} (designated by @samp{'}) is used for
syntactic operators that are considered as part of an expression if they
appear next to one. In Lisp modes, these characters include the
apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
macros), and @samp{#} (used in the read syntax for certain data types).
1994-03-28 05:41:05 +00:00
@end deffn
@deffn {Syntax class} @w{comment starter}
@deffnx {Syntax class} @w{comment ender}
@cindex comment syntax
The @dfn{comment starter} and @dfn{comment ender} characters are used in
various languages to delimit comments. These classes are designated
1998-02-28 01:53:53 +00:00
by @samp{<} and @samp{>}, respectively.
1994-03-28 05:41:05 +00:00
English text has no comment characters. In Lisp, the semicolon
(@samp{;}) starts a comment and a newline or formfeed ends one.
@end deffn
@deffn {Syntax class} @w{inherit}
1998-02-28 01:53:53 +00:00
This syntax class does not specify a particular syntax. It says to look
in the standard syntax table to find the syntax of this character. The
1994-03-28 05:41:05 +00:00
designator for this syntax code is @samp{@@}.
@end deffn
1998-02-28 01:53:53 +00:00
@deffn {Syntax class} @w{generic comment delimiter}
A @dfn{generic comment delimiter} character starts or ends a special
kind of comment. @emph{Any} generic comment delimiter matches
@emph{any} generic comment delimiter, but they cannot match a comment
starter or comment ender; generic comment delimiters can only match each
other.
This syntax class is primarily meant for use with the
@code{syntax-table} text property (@pxref{Syntax Properties}). You can
mark any range of characters as forming a comment, by giving the first
and last characters of the range @code{syntax-table} properties
identifying them as generic comment delimiters.
@end deffn
@deffn {Syntax class} @w{generic string delimiter}
A @dfn{generic string delimiter} character starts or ends a string.
This class differs from the string quote class in that @emph{any}
generic string delimiter can match any other generic string delimiter;
but they do not match ordinary string quote characters.
This syntax class is primarily meant for use with the
@code{syntax-table} text property (@pxref{Syntax Properties}). You can
mark any range of characters as forming a string constant, by giving the
first and last characters of the range @code{syntax-table} properties
identifying them as generic string delimiters.
@end deffn
1994-03-28 05:41:05 +00:00
@node Syntax Flags
@subsection Syntax Flags
@cindex syntax flags
In addition to the classes, entries for characters in a syntax table
1999-11-01 15:52:18 +00:00
can specify flags. There are seven possible flags, represented by the
characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n},
and @samp{p}.
All the flags except @samp{n} and @samp{p} are used to describe
multi-character comment delimiters. The digit flags indicate that a
character can @emph{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 @samp{*} in C mode, which is a punctuation character, @emph{and}
the second character of a start-of-comment sequence (@samp{/*}),
@emph{and} the first character of an end-of-comment sequence
(@samp{*/}).
1994-03-28 05:41:05 +00:00
1998-02-28 01:53:53 +00:00
Here is a table of the possible flags for a character @var{c},
and what they mean:
1994-03-28 05:41:05 +00:00
@itemize @bullet
@item
1994-08-07 00:25:52 +00:00
@samp{1} means @var{c} is the start of a two-character comment-start
1994-03-28 05:41:05 +00:00
sequence.
@item
@samp{2} means @var{c} is the second character of such a sequence.
@item
1994-08-07 00:25:52 +00:00
@samp{3} means @var{c} is the start of a two-character comment-end
1994-03-28 05:41:05 +00:00
sequence.
@item
@samp{4} means @var{c} is the second character of such a sequence.
@item
@c Emacs 19 feature
@samp{b} means that @var{c} as a comment delimiter belongs to the
alternative ``b'' comment style.
Emacs supports two comment styles simultaneously in any one syntax
table. This is for the sake of C++. Each style of comment syntax has
its own comment-start sequence and its own comment-end sequence. Each
comment must stick to one style or the other; thus, if it starts with
the comment-start sequence of style ``b'', it must also end with the
comment-end sequence of style ``b''.
The two comment-start sequences must begin with the same character; only
the second character may differ. Mark the second character of the
1994-08-07 00:25:52 +00:00
``b''-style comment-start sequence with the @samp{b} flag.
1994-03-28 05:41:05 +00:00
A comment-end sequence (one or two characters) applies to the ``b''
style if its first character has the @samp{b} flag set; otherwise, it
applies to the ``a'' style.
The appropriate comment syntax settings for C++ are as follows:
@table @asis
@item @samp{/}
@samp{124b}
@item @samp{*}
@samp{23}
@item newline
@samp{>b}
@end table
1994-08-07 00:25:52 +00:00
This defines four comment-delimiting sequences:
@table @asis
@item @samp{/*}
This is a comment-start sequence for ``a'' style because the
second character, @samp{*}, does not have the @samp{b} flag.
@item @samp{//}
This is a comment-start sequence for ``b'' style because the second
character, @samp{/}, does have the @samp{b} flag.
@item @samp{*/}
This is a comment-end sequence for ``a'' style because the first
1998-05-26 18:56:56 +00:00
character, @samp{*}, does not have the @samp{b} flag.
1994-08-07 00:25:52 +00:00
@item newline
This is a comment-end sequence for ``b'' style, because the newline
character has the @samp{b} flag.
@end table
1994-03-28 05:41:05 +00:00
1999-11-01 15:52:18 +00:00
@item
@samp{n} on a comment delimiter character specifies
that this kind of comment can be nested. For a two-character
comment delimiter, @samp{n} on either character makes it
nestable.
1994-03-28 05:41:05 +00:00
@item
@c Emacs 19 feature
@samp{p} identifies an additional ``prefix character'' for Lisp syntax.
These characters are treated as whitespace when they appear between
expressions. When they appear within an expression, they are handled
according to their usual syntax codes.
The function @code{backward-prefix-chars} moves back over these
characters, as well as over characters whose primary syntax class is
prefix (@samp{'}). @xref{Motion and Syntax}.
@end itemize
@node Syntax Table Functions
@section Syntax Table Functions
In this section we describe functions for creating, accessing and
altering syntax tables.
@defun make-syntax-table
1998-04-20 17:43:57 +00:00
This function creates a new syntax table. It inherits the syntax for
letters and control characters from the standard syntax table. For
other characters, the syntax is copied from the standard syntax table.
1994-03-28 05:41:05 +00:00
Most major mode syntax tables are created in this way.
@end defun
@defun copy-syntax-table &optional table
This function constructs a copy of @var{table} and returns it. If
@var{table} is not supplied (or is @code{nil}), it returns a copy of the
current syntax table. Otherwise, an error is signaled if @var{table} is
not a syntax table.
@end defun
@deffn Command modify-syntax-entry char syntax-descriptor &optional table
This function sets the syntax entry for @var{char} according to
@var{syntax-descriptor}. The syntax is changed only for @var{table},
which defaults to the current buffer's syntax table, and not in any
other syntax table. The argument @var{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. @xref{Syntax Descriptors}.
This function always returns @code{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 @var{char} is not a character.
@example
@group
@exdent @r{Examples:}
;; @r{Put the space character in class whitespace.}
(modify-syntax-entry ?\ " ")
@result{} nil
@end group
@group
;; @r{Make @samp{$} an open parenthesis character,}
;; @r{with @samp{^} as its matching close.}
(modify-syntax-entry ?$ "(^")
@result{} nil
@end group
@group
;; @r{Make @samp{^} a close parenthesis character,}
;; @r{with @samp{$} as its matching open.}
(modify-syntax-entry ?^ ")$")
@result{} nil
@end group
@group
;; @r{Make @samp{/} a punctuation character,}
;; @r{the first character of a start-comment sequence,}
;; @r{and the second character of an end-comment sequence.}
;; @r{This is used in C mode.}
1994-08-07 00:25:52 +00:00
(modify-syntax-entry ?/ ". 14")
1994-03-28 05:41:05 +00:00
@result{} nil
@end group
@end example
@end deffn
@defun char-syntax character
This function returns the syntax class of @var{character}, represented
1998-02-28 01:53:53 +00:00
by its mnemonic designator character. This returns @emph{only} the
1994-03-28 05:41:05 +00:00
class, not any matching parenthesis or flags.
An error is signaled if @var{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 @samp{/} is punctuation. This
1994-08-07 00:25:52 +00:00
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
1994-03-28 05:41:05 +00:00
of open parentheses. This does not show the fact that it has a matching
character, @samp{)}.
@example
@group
1998-04-20 17:43:57 +00:00
(string (char-syntax ?\ ))
1994-03-28 05:41:05 +00:00
@result{} " "
@end group
@group
1998-04-20 17:43:57 +00:00
(string (char-syntax ?/))
1994-03-28 05:41:05 +00:00
@result{} "."
@end group
@group
1998-04-20 17:43:57 +00:00
(string (char-syntax ?\())
1994-03-28 05:41:05 +00:00
@result{} "("
@end group
@end example
1998-04-20 17:43:57 +00:00
We use @code{string} to make it easier to see the character returned by
@code{char-syntax}.
1994-03-28 05:41:05 +00:00
@end defun
@defun set-syntax-table table
This function makes @var{table} the syntax table for the current buffer.
It returns @var{table}.
@end defun
@defun syntax-table
This function returns the current syntax table, which is the table for
the current buffer.
@end defun
1999-12-03 19:11:12 +00:00
@defmac with-syntax-table @var{table} @var{body}...
@tindex with-syntax-table
This macro executes @var{body} using @var{table} as the current syntax
table. It returns the value of the last form in @var{body}, after
restoring the old current syntax table.
Since each buffer has its own current syntax table, we should make that
more precise: @code{with-syntax-table} temporarily alters the current
syntax table of whichever buffer is current at the time the macro
execution starts. Other buffers are not affected.
@end defmac
1998-02-28 01:53:53 +00:00
@node Syntax Properties
@section Syntax Properties
@kindex syntax-table @r{(text property)}
When the syntax table is not flexible enough to specify the syntax of a
language, you can use @code{syntax-table} text properties to override
the syntax table for specific character occurrences in the buffer.
@xref{Text Properties}.
1998-04-20 17:43:57 +00:00
The valid values of @code{syntax-table} text property are:
1998-02-28 01:53:53 +00:00
@table @asis
@item @var{syntax-table}
If the property value is a syntax table, that table is used instead of
the current buffer's syntax table to determine the syntax for this
occurrence of the character.
@item @code{(@var{syntax-code} . @var{matching-char})}
A cons cell of this format specifies the syntax for this
occurrence of the character.
@item @code{nil}
If the property is @code{nil}, the character's syntax is determined from
the current syntax table in the usual way.
@end table
@defvar parse-sexp-lookup-properties
1998-05-19 03:45:57 +00:00
@tindex parse-sexp-lookup-properties
1998-02-28 01:53:53 +00:00
If this is non-@code{nil}, the syntax scanning functions pay attention
to syntax text properties. Otherwise they use only the current syntax
table.
@end defvar
1994-03-28 05:41:05 +00:00
@node Motion and Syntax
@section Motion and Syntax
1998-04-20 17:43:57 +00:00
This section describes functions for moving across characters that
have certain syntax classes.
1994-03-28 05:41:05 +00:00
@defun skip-syntax-forward syntaxes &optional limit
This function moves point forward across characters having syntax classes
mentioned in @var{syntaxes}. It stops when it encounters the end of
1994-08-07 00:25:52 +00:00
the buffer, or position @var{limit} (if specified), or a character it is
1994-03-28 05:41:05 +00:00
not supposed to skip.
1999-09-17 06:59:04 +00:00
If @var{syntaxes} starts with @samp{^}, then the function skips
characters whose syntax is @emph{not} in @var{syntaxes}.
1994-03-28 05:41:05 +00:00
The return value is the distance traveled, which is a nonnegative
integer.
@end defun
@defun skip-syntax-backward syntaxes &optional limit
This function moves point backward across characters whose syntax
classes are mentioned in @var{syntaxes}. It stops when it encounters
1999-09-17 06:59:04 +00:00
the beginning of the buffer, or position @var{limit} (if specified), or
a character it is not supposed to skip.
If @var{syntaxes} starts with @samp{^}, then the function skips
characters whose syntax is @emph{not} in @var{syntaxes}.
1998-05-26 18:56:56 +00:00
1994-03-28 05:41:05 +00:00
The return value indicates the distance traveled. It is an integer that
is zero or less.
@end defun
@defun backward-prefix-chars
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 @samp{p} flag.
@end defun
@node Parsing Expressions
@section Parsing Balanced Expressions
Here are several functions for parsing and scanning balanced
expressions, also known as @dfn{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. @xref{List Motion}, for convenient
higher-level functions for moving over balanced expressions.
@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
This function parses a sexp in the current buffer starting at
1994-08-07 00:25:52 +00:00
@var{start}, not scanning past @var{limit}. It stops at position
@var{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.
1994-03-28 05:41:05 +00:00
If @var{state} is @code{nil}, @var{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 @var{state}
argument that describes the initial status of parsing.
@cindex parenthesis depth
If the third argument @var{target-depth} is non-@code{nil}, parsing
stops if the depth in parentheses becomes equal to @var{target-depth}.
The depth starts at 0, or at whatever is given in @var{state}.
If the fourth argument @var{stop-before} is non-@code{nil}, parsing
stops when it comes to any character that starts a sexp. If
@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
1998-02-28 01:53:53 +00:00
start of a comment. If @var{stop-comment} is the symbol
@code{syntax-table}, parsing stops after the start of a comment or a
1998-05-26 18:56:56 +00:00
string, or the end of a comment or a string, whichever comes first.
1994-03-28 05:41:05 +00:00
@cindex parse state
1998-02-28 01:53:53 +00:00
The fifth argument @var{state} is a nine-element list of the same form
1998-04-20 17:43:57 +00:00
as the value of this function, described below. (It is OK to omit the
1998-02-28 01:53:53 +00:00
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
@code{parse-partial-sexp}.
1994-03-28 05:41:05 +00:00
1998-02-28 01:53:53 +00:00
The result is a list of nine elements describing the final state of
1994-03-28 05:41:05 +00:00
the parse:
@enumerate 0
@item
The depth in parentheses, counting from 0.
@item
@cindex innermost containing parentheses
1994-08-07 00:25:52 +00:00
The character position of the start of the innermost parenthetical
grouping containing the stopping point; @code{nil} if none.
1994-03-28 05:41:05 +00:00
@item
@cindex previous complete subexpression
The character position of the start of the last complete subexpression
terminated; @code{nil} if none.
@item
@cindex inside string
Non-@code{nil} if inside a string. More precisely, this is the
1998-02-28 01:53:53 +00:00
character that will terminate the string, or @code{t} if a generic
string delimiter character should terminate it.
1994-03-28 05:41:05 +00:00
@item
@cindex inside comment
1999-11-01 15:52:18 +00:00
@code{t} if inside a comment (of either style),
or the comment nesting level if inside a kind of comment
that can be nested.
1994-03-28 05:41:05 +00:00
@item
@cindex quote character
@code{t} if point is just after a quote character.
@item
The minimum parenthesis depth encountered during this scan.
@item
1998-02-28 01:53:53 +00:00
What kind of comment is active: @code{nil} for a comment of style ``a'',
@code{t} for a comment of style ``b'', and @code{syntax-table} for
a comment that should be ended by a generic comment delimiter character.
@item
The string or comment start position. While inside a comment, this is
the position where the comment began; while inside a string, this is the
position where the string began. When outside of strings and comments,
this element is @code{nil}.
1994-03-28 05:41:05 +00:00
@end enumerate
Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
@cindex indenting with parentheses
This function is most often used to compute indentation for languages
that have nested parentheses.
@end defun
@defun scan-lists from count depth
This function scans forward @var{count} balanced parenthetical groupings
1998-02-28 01:53:53 +00:00
from position @var{from}. It returns the position where the scan stops.
If @var{count} is negative, the scan moves backwards.
1994-03-28 05:41:05 +00:00
If @var{depth} is nonzero, parenthesis depth counting begins from that
value. The only candidates for stopping are places where the depth in
parentheses becomes zero; @code{scan-lists} counts @var{count} such
places and then stops. Thus, a positive value for @var{depth} means go
1994-08-07 00:25:52 +00:00
out @var{depth} levels of parenthesis.
1994-03-28 05:41:05 +00:00
Scanning ignores comments if @code{parse-sexp-ignore-comments} is
non-@code{nil}.
1994-08-07 00:25:52 +00:00
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, @code{nil} is
returned.
1994-03-28 05:41:05 +00:00
@end defun
@defun scan-sexps from count
1998-02-28 01:53:53 +00:00
This function scans forward @var{count} sexps from position @var{from}.
It returns the position where the scan stops. If @var{count} is
negative, the scan moves backwards.
1994-03-28 05:41:05 +00:00
Scanning ignores comments if @code{parse-sexp-ignore-comments} is
non-@code{nil}.
1994-08-07 00:25:52 +00:00
If the scan reaches the beginning or end of (the accessible part of) the
1998-02-28 01:53:53 +00:00
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, @code{nil} is returned.
1994-03-28 05:41:05 +00:00
@end defun
@defvar parse-sexp-ignore-comments
@cindex skipping comments
If the value is non-@code{nil}, then comments are treated as
whitespace by the functions in this section and by @code{forward-sexp}.
In older Emacs versions, this feature worked only when the comment
terminator is something like @samp{*/}, and appears only to end a
comment. In languages where newlines terminate comments, it was
necessary make this variable @code{nil}, since not every newline is the
end of a comment. This limitation no longer exists.
@end defvar
You can use @code{forward-comment} to move forward or backward over
one comment or several comments.
@defun forward-comment count
This function moves point forward across @var{count} comments (backward,
if @var{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 @var{count}.
@end defun
To move forward over all comments and whitespace following point, use
@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good
1994-08-07 00:25:52 +00:00
argument to use, because the number of comments in the buffer cannot
1994-03-28 05:41:05 +00:00
exceed that many.
@node Standard Syntax Tables
@section Some Standard Syntax Tables
1995-06-06 19:21:15 +00:00
Most of the major modes in Emacs have their own syntax tables. Here
are several of them:
1994-03-28 05:41:05 +00:00
@defun standard-syntax-table
This function returns the standard syntax table, which is the syntax
table used in Fundamental mode.
@end defun
@defvar text-mode-syntax-table
The value of this variable is the syntax table used in Text mode.
@end defvar
@defvar c-mode-syntax-table
The value of this variable is the syntax table for C-mode buffers.
@end defvar
@defvar 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 @code{read}
function.)
@end defvar
@node Syntax Table Internals
@section Syntax Table Internals
@cindex syntax table internals
1998-02-28 01:53:53 +00:00
Lisp programs don't usually work with the elements directly; the
1994-03-28 05:41:05 +00:00
Lisp-level syntax table functions usually work with syntax descriptors
1998-02-28 01:53:53 +00:00
(@pxref{Syntax Descriptors}). Nonetheless, here we document the
internal format.
Each element of a syntax table is a cons cell of the form
@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car},
@var{syntax-code}, is an integer that encodes the syntax class, and any
flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if
a character to match was specified.
1994-03-28 05:41:05 +00:00
1998-02-28 01:53:53 +00:00
This table gives the value of @var{syntax-code} which corresponds
to each syntactic type.
1994-03-28 05:41:05 +00:00
1998-04-20 17:43:57 +00:00
@multitable @columnfractions .05 .3 .3 .3
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
0 @ @ whitespace
@tab
5 @ @ close parenthesis
@tab
10 @ @ character quote
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
1 @ @ punctuation
@tab
6 @ @ expression prefix
@tab
11 @ @ comment-start
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
2 @ @ word
@tab
7 @ @ string quote
@tab
12 @ @ comment-end
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
3 @ @ symbol
@tab
8 @ @ paired delimiter
@tab
13 @ @ inherit
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
4 @ @ open parenthesis
@tab
9 @ @ escape
@tab
14 @ @ comment-fence
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
15 @ string-fence
@end multitable
1994-03-28 05:41:05 +00:00
1998-02-28 01:53:53 +00:00
For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
(41 is the character code for @samp{)}.)
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.
1998-04-20 17:43:57 +00:00
@multitable @columnfractions .05 .3 .3 .3
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
@samp{1} @ @ @code{(lsh 1 16)}
@tab
1999-11-01 15:52:18 +00:00
@samp{4} @ @ @code{(lsh 1 19)}
1998-04-20 17:43:57 +00:00
@tab
1999-11-01 15:52:18 +00:00
@samp{b} @ @ @code{(lsh 1 21)}
1998-05-19 03:45:57 +00:00
@item
@tab
1998-04-20 17:43:57 +00:00
@samp{2} @ @ @code{(lsh 1 17)}
@tab
1999-11-01 15:52:18 +00:00
@samp{p} @ @ @code{(lsh 1 20)}
1998-04-20 17:43:57 +00:00
@tab
1999-11-01 15:52:18 +00:00
@samp{n} @ @ @code{(lsh 1 22)}
@item
@tab
@samp{3} @ @ @code{(lsh 1 18)}
1998-04-20 17:43:57 +00:00
@end multitable
1998-02-28 01:53:53 +00:00
@node Categories
@section Categories
@cindex categories of characters
@dfn{Categories} provide an alternate way of classifying characters
1998-04-20 17:43:57 +00:00
syntactically. You can define several categories as needed, then
independently assign each character to one or more categories. Unlike
1998-02-28 01:53:53 +00:00
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.
Each buffer has a @dfn{category table} which records which categories
are defined and also which characters belong to each category. Each
1998-04-20 17:43:57 +00:00
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.
1999-09-17 06:59:04 +00:00
Each category has a name, which is an @sc{ascii} printing character in
1998-04-20 17:43:57 +00:00
the range @w{@samp{ }} to @samp{~}. You specify the name of a category
when you define it with @code{define-category}.
1998-02-28 01:53:53 +00:00
The category table is actually a char-table (@pxref{Char-Tables}).
The element of the category table at index @var{c} is a @dfn{category
set}---a bool-vector---that indicates which categories character @var{c}
belongs to. In this category set, if the element at index @var{cat} is
@code{t}, that means category @var{cat} is a member of the set, and that
character @var{c} belongs to category @var{cat}.
@defun define-category char docstring &optional table
This function defines a new category, with name @var{char} and
documentation @var{docstring}.
The new category is defined for category table @var{table}, which
defaults to the current buffer's category table.
@end defun
@defun category-docstring category &optional table
This function returns the documentation string of category @var{category}
in category table @var{table}.
@example
(category-docstring ?a)
@result{} "ASCII"
(category-docstring ?l)
@result{} "Latin"
@end example
@end defun
@defun get-unused-category table
This function returns a category name (a character) which is not
1998-04-20 17:43:57 +00:00
currently defined in @var{table}. If all possible categories are in use
1998-05-26 18:56:56 +00:00
in @var{table}, it returns @code{nil}.
1998-02-28 01:53:53 +00:00
@end defun
@defun category-table
This function returns the current buffer's category table.
@end defun
@defun category-table-p object
This function returns @code{t} if @var{object} is a category table,
otherwise @code{nil}.
@end defun
@defun standard-category-table
This function returns the standard category table.
@end defun
@defun copy-category-table &optional table
This function constructs a copy of @var{table} and returns it. If
@var{table} is not supplied (or is @code{nil}), it returns a copy of the
current category table. Otherwise, an error is signaled if @var{table}
is not a category table.
@end defun
@defun set-category-table table
This function makes @var{table} the category table for the current
buffer. It returns @var{table}.
@end defun
1999-12-03 19:11:12 +00:00
@defun make-category-table &optional default-set
@tindex make-category-table
This creates and returns an empty category table, using
@var{default-set} as the default (for characters that don't specify
their own sets). Initially no characters specify their own sets in this
new table; that is what we mean by ``empty.''
@end defun
1998-02-28 01:53:53 +00:00
@defun make-category-set categories
This function returns a new category set---a bool-vector---whose initial
contents are the categories listed in the string @var{categories}. The
elements of @var{categories} should be category names; the new category
set has @code{t} for each of those categories, and @code{nil} for all
other categories.
@example
(make-category-set "al")
@result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@end defun
@defun char-category-set char
This function returns the category set for character @var{char}. This
is the bool-vector which records which categories the character
@var{char} belongs to. The function @code{char-category-set} does not
allocate storage, because it returns the same bool-vector that exists in
the category table.
@example
(char-category-set ?a)
@result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@end defun
@defun category-set-mnemonics category-set
This function converts the category set @var{category-set} into a string
1999-12-03 19:11:12 +00:00
containing the characters that designate the categories that are members
of the set.
1998-02-28 01:53:53 +00:00
@example
(category-set-mnemonics (char-category-set ?a))
@result{} "al"
@end example
@end defun
@defun modify-category-entry character category &optional table reset
This function modifies the category set of @var{character} in category
table @var{table} (which defaults to the current buffer's category
table).
Normally, it modifies the category set by adding @var{category} to it.
But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun