@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/syntax.info
@node Syntax Tables, Abbrevs, Searching and Matching, Top
this chapter.
@end ifinfo
- Under XEmacs 20, a syntax table is a particular subtype of the
+ Under XEmacs 20 and later, a syntax table is a particular subtype of the
primitive char table type (@pxref{Char Tables}), 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
their meanings, and examples of their use.
@deffn {Syntax class} @w{whitespace character}
-@dfn{Whitespace characters} (designated with @w{@samp{@ }} or @samp{-})
+@dfn{Whitespace characters} (designated with @samp{-})
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.
+newline and formfeed are almost always classified as whitespace. (The
+designator @w{@samp{@ }} is accepted for backwards compatibility with
+older versions of XEmacs, but is deprecated. It is invalid in GNU Emacs.)
@end deffn
@deffn {Syntax class} @w{word constituent}
@subsection Syntax Flags
@cindex syntax flags
+@c This is a bit inaccurate, the ``a'' and ``b'' flags actually don't
+@c exist in the internal implementation. AFAICT it doesn't affect the
+@c semantics as perceived by the LISP programmer.
In addition to the classes, entries for characters in a syntax table
-can include flags. There are six possible flags, represented by the
-characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b} and
-@samp{p}.
-
- All the flags except @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
+can include flags. There are eleven possible flags, represented by the
+digits @samp{1}--@samp{8}, and the lowercase letters @samp{a}, @samp{b},
+and @samp{p}.
+
+ All the flags except @samp{p} are used to describe comment delimiters.
+The digit flags indicate that a character can @emph{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 @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{*/}).
+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''.
+
+@c #### Compatibility note; index here.
+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 @samp{b} flag, XEmacs
+uses the digit flags @samp{5}--@samp{8}.
+
+A one character comment-end sequence applies to the ``b'' style if its
+first character has the @samp{b} flag set; otherwise, it applies to the
+``a'' style. The @samp{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 @var{c} are:
@itemize @bullet
@item
@samp{1} means @var{c} is the start of a two-character comment-start
-sequence.
+sequence of style ``a''.
@item
@samp{2} means @var{c} is the second character of such a sequence.
@item
@samp{3} means @var{c} is the start of a two-character comment-end
-sequence.
+sequence of style ``a''.
@item
@samp{4} means @var{c} is the second character of such a sequence.
@item
+@samp{5} means @var{c} is the start of a two-character comment-start
+sequence of style ``b''.
+
+@item
+@samp{6} means @var{c} is the second character of such a sequence.
+
+@item
+@samp{7} means @var{c} is the start of a two-character comment-end
+sequence of style ``b''.
+
+@item
+@samp{8} means @var{c} is the second character of such a sequence.
+
+@item
+@samp{a} means that @var{c} as a comment delimiter belongs to the
+default ``a'' comment style. (This flag is optional.)
+
+@item
@c Emacs 19 feature
@samp{b} means that @var{c} as a comment delimiter belongs to the
-alternative ``b'' comment style.
+alternate ``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''.
+@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 two comment-start sequences must begin with the same character; only
-the second character may differ. Mark the second character of the
-``b''-style comment-start sequence with the @samp{b} flag.
+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
+
+Lisp (as you would expect) has a simple comment syntax.
+
+@table @asis
+@item @samp{;}
+@samp{<}
+@item newline
+@samp{>}
+@end table
+
+Note that no flags are used.
+This defines two comment-delimiting sequences:
-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.
+@table @asis
+@item @samp{;}
+This is a single-character comment-start sequence because the syntax
+class is @samp{<}.
+
+@item newline
+This is a single character comment-end sequence because the syntax class
+is @samp{>} and the @samp{b} flag is not set.
+@end table
-The appropriate comment syntax settings for C++ are as follows:
+C++ (again, as you would expect) has a baroque, overrich, and
+excessively complex comment syntax.
@table @asis
@item @samp{/}
-@samp{124b}
+@samp{1456}
@item @samp{*}
@samp{23}
@item newline
@samp{>b}
@end table
-This defines four comment-delimiting sequences:
+Note that the ``b'' style mixes one-character and two-character
+sequences. The table above 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.
+This is a comment-start sequence for ``a'' style because the @samp{1}
+flag is set on @samp{/} and the @samp{2} flag is set on @samp{*}.
@item @samp{//}
-This is a comment-start sequence for ``b'' style because the second
-character, @samp{/}, does have the @samp{b} flag.
+This is a comment-start sequence for ``b'' style because both the @samp{5}
+and the @samp{6} flags are set on @samp{/}.
@item @samp{*/}
-This is a comment-end sequence for ``a'' style because the first
-character, @samp{*}, does not have the @samp{b} flag
+This is a comment-end sequence for ``a'' style because the @samp{3}
+flag is set on @samp{*} and the @samp{4} flag is set on @samp{/}.
@item newline
This is a comment-end sequence for ``b'' style, because the newline
character has the @samp{b} flag.
@end table
-@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 &optional table
+@defun 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
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.
+@defun copy-syntax-table &optional syntax-table
+This function constructs a copy of @var{syntax-table} and returns it.
+If @var{syntax-table} is not supplied (or is @code{nil}), it returns a
+copy of the current syntax table. Otherwise, an error is signaled if
+@var{syntax-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}.
+@deffn Command modify-syntax-entry char-range syntax-descriptor &optional syntax-table
+This function sets the syntax entry for @var{char-range} according to
+@var{syntax-descriptor}. @var{char-range} is either a single character
+or a range of characters, as used with @code{put-char-table}. The syntax
+is changed only for @var{syntax-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.
+the table for @var{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. An error is also
-signaled if @var{char} is not a character.
+one of the twelve syntax class designator characters.
@example
@group
@end example
@end deffn
-@defun char-syntax character
+@defun char-syntax character &optional syntax-table
This function returns the syntax class of @var{character}, represented
by its mnemonic designator character. This @emph{only} returns the
class, not any matching parenthesis or flags.
-An error is signaled if @var{char} is not a character.
+An error is signaled if @var{character} is not a character.
+
+The characters that correspond to various syntax codes
+are listed in the documentation of @code{modify-syntax-entry}.
+
+Optional second argument @var{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
@end example
@end defun
-@defun set-syntax-table table &optional buffer
-This function makes @var{table} the syntax table for @var{buffer}, which
-defaults to the current buffer if omitted. It returns @var{table}.
+@defun set-syntax-table syntax-table &optional buffer
+This function makes @var{syntax-table} the syntax table for @var{buffer}, which
+defaults to the current buffer if omitted. It returns @var{syntax-table}.
@end defun
@defun syntax-table &optional buffer
the parse:
@enumerate 0
-@item
+@item
The depth in parentheses, counting from 0.
-@item
+@item
@cindex innermost containing parentheses
The character position of the start of the innermost parenthetical
grouping containing the stopping point; @code{nil} if none.
-@item
+@item
@cindex previous complete subexpression
The character position of the start of the last complete subexpression
terminated; @code{nil} if none.
-@item
+@item
@cindex inside string
Non-@code{nil} if inside a string. More precisely, this is the
character that will terminate the string.
-@item
+@item
@cindex inside comment
@code{t} if inside a comment (of either style).
-@item
+@item
@cindex quote character
@code{t} if point is just after a quote character.
-@item
+@item
The minimum parenthesis depth encountered during this scan.
@item
You can use @code{forward-comment} to move forward or backward over
one comment or several comments.
-@defun forward-comment count &optional buffer
+@defun forward-comment &optional count buffer
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}.
+It also stops after satisfying @var{count}. @var{count} defaults to @code{1}.
- Optional argument @var{buffer} defaults to the current buffer.
+Optional argument @var{buffer} defaults to the current buffer.
@end defun
To move forward over all comments and whitespace following point, use