@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/syntax
@node Syntax Tables, Abbrevs, Searching and Matching, Top
@node Syntax Basics
@section Syntax Table Concepts
-@ifinfo
+@ifnottex
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
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
+@end ifnottex
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
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.
+character affects all syntax tables that inherit from it.
@defun syntax-table-p object
This function returns @code{t} if @var{object} is a syntax 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,
+designator character is one that is often assigned that class; however,
its meaning as a designator is unvarying and independent of what syntax
-that character currently has.
+that character currently has. Thus, @samp{\} as a designator character
+always gives ``escape character'' syntax, regardless of what syntax
+@samp{\} currently has.
@cindex syntax descriptor
A syntax descriptor is a Lisp string that specifies a syntax class, a
For example, the syntax descriptor for the character @samp{*} in C
mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
-unused, second character of a comment-starter, first character of an
+unused, second character of a comment-starter, first character of a
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).
@end deffn
@deffn {Syntax class} @w{word constituent}
-@dfn{Word constituents} (designated by @samp{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.
+@dfn{Word constituents} (designated by @samp{w}) are parts of words in
+human languages, and are typically used in variable and command names
+in programs. All upper- and lower-case letters, and the digits, are
+typically word constituents.
@end deffn
@deffn {Syntax class} @w{symbol constituent}
@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
+Some programming language modes, such as Emacs Lisp mode, have no
characters in this class since the few characters that are not symbol or
-word constituents all have other uses.
+word constituents all have other uses. Other programming language modes,
+such as C mode, use punctuation syntax for operators.
@end deffn
@deffn {Syntax class} @w{open parenthesis character}
@deffn {Syntax class} @w{inherit}
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
-designator for this syntax code is @samp{@@}.
+designator for this syntax class is @samp{@@}.
@end deffn
@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.
+A @dfn{generic comment delimiter} (designated by @samp{!}) 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
@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.
+A @dfn{generic string delimiter} (designated by @samp{|}) 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
@cindex syntax flags
In addition to the classes, entries for characters in a syntax table
-can specify 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
-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{*/}).
+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{*/}).
Here is a table of the possible flags for a character @var{c},
and what they mean:
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 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
@item @samp{*/}
This is a comment-end sequence for ``a'' style because the first
-character, @samp{*}, does not have the @samp{b} flag
+character, @samp{*}, does not have the @samp{b} flag.
@item newline
This is a comment-end sequence for ``b'' style, because the newline
character has the @samp{b} flag.
@end table
+@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.
+
@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.
+according to their usual syntax classes.
The function @code{backward-prefix-chars} moves back over these
characters, as well as over characters whose primary syntax class is
In this section we describe functions for creating, accessing and
altering syntax tables.
-@defun make-syntax-table
-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.
+@defun make-syntax-table &optional table
+This function creates a new syntax table, with all values initialized
+to @code{nil}. If @var{table} is non-@code{nil}, it becomes the
+parent of the new syntax table, otherwise the standard syntax table is
+the parent. Like all char-tables, a syntax table inherits from its
+parent. Thus the original syntax of all characters in the returned
+syntax table is determined by the parent. @xref{Char-Tables}.
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
+standard syntax table. Otherwise, an error is signaled if @var{table} is
not a syntax table.
@end defun
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
+one of the seventeen syntax class designator characters. An error is also
signaled if @var{char} is not a character.
@example
@exdent @r{Examples:}
;; @r{Put the space character in class whitespace.}
-(modify-syntax-entry ?\ " ")
+(modify-syntax-entry ?\s " ")
@result{} nil
@end group
@example
@group
-(string (char-syntax ?\ ))
+(string (char-syntax ?\s))
@result{} " "
@end group
the current buffer.
@end defun
+@defmac with-syntax-table @var{table} @var{body}@dots{}
+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
+
@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}.
+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}. You can use Font Lock mode to set
+@code{syntax-table} text properties. @xref{Setting Syntax
+Properties}.
The valid values of @code{syntax-table} text property are:
@item @code{(@var{syntax-code} . @var{matching-char})}
A cons cell of this format specifies the syntax for this
-occurrence of the character.
+occurrence of the character. (@pxref{Syntax Table Internals})
@item @code{nil}
If the property is @code{nil}, the character's syntax is determined from
@end table
@defvar parse-sexp-lookup-properties
-@tindex parse-sexp-lookup-properties
If this is non-@code{nil}, the syntax scanning functions pay attention
to syntax text properties. Otherwise they use only the current syntax
table.
have certain syntax classes.
@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
-the buffer, or position @var{limit} (if specified), or a character it is
-not supposed to skip.
-@ignore @c may want to change this.
+This function moves point forward across characters having syntax
+classes mentioned in @var{syntaxes} (a string of syntax class
+characters). It stops when it encounters the end 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}.
+
The return value is the distance traveled, which is a nonnegative
integer.
-@end ignore
@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
-the beginning of the buffer, or position @var{limit} (if specified), or a
-character it is not supposed to skip.
-@ignore @c may want to change this.
+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}.
+
The return value indicates the distance traveled. It is an integer that
is zero or less.
-@end ignore
@end defun
@defun backward-prefix-chars
@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
+@section Parsing Expressions
+
+ This section describes functions for parsing and scanning balanced
+expressions, also known as @dfn{sexps}. Basically, a sexp is either a
+balanced parenthetical grouping, a string, or a symbol name (a
+sequence of characters whose syntax is either word constituent or
+symbol constituent). However, characters whose syntax is expression
+prefix are treated as part of the sexp if they appear next to it.
+
+ 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
-@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.
+ A character's syntax controls how it changes the state of the
+parser, rather than describing the state itself. For example, a
+string delimiter character toggles the parser state between
+``in-string'' and ``in-code,'' but the syntax of characters does not
+directly say whether they are inside a string. For example (note that
+15 is the syntax code for generic string delimiters),
-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.
+@example
+(put-text-property 1 9 'syntax-table '(15 . nil))
+@end example
-@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}.
+@noindent
+does not tell Emacs that the first eight chars of the current buffer
+are a string, but rather that they are all string delimiters. As a
+result, Emacs treats them as four consecutive empty string constants.
-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
-start of a comment. If @var{stop-comment} is the symbol
-@code{syntax-table}, parsing stops after the start of a comment or a
-string, or the of a comment or a string, whichever comes first.
+@menu
+* Motion via Parsing:: Motion functions that work by parsing.
+* Position Parse:: Determining the syntactic state of a position.
+* Parser State:: How Emacs represents a syntactic state.
+* Low-Level Parsing:: Parsing across a specified region.
+* Control Parsing:: Parameters that affect parsing.
+@end menu
+
+@node Motion via Parsing
+@subsection Motion Commands Based on Parsing
+
+ This section describes simple point-motion functions that operate
+based on parsing expressions.
+
+@defun scan-lists from count depth
+This function scans forward @var{count} balanced parenthetical groupings
+from position @var{from}. It returns the position where the scan stops.
+If @var{count} is negative, the scan moves backwards.
+
+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
+out @var{depth} levels of parenthesis.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{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, @code{nil} is
+returned.
+@end defun
+
+@defun scan-sexps from count
+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.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{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, @code{nil} is returned.
+@end defun
+
+@defun forward-comment count
+This function moves point forward across @var{count} complete comments
+ (that is, including the starting delimiter and the terminating
+delimiter if any), plus any whitespace encountered on the way. It
+moves backward if @var{count} is negative. If it encounters anything
+other than a comment or whitespace, it stops, leaving point at the
+place where it stopped. This includes (for instance) finding the end
+of a comment when moving forward and expecting the beginning of one.
+The function also stops immediately after moving over the specified
+number of complete comments. If @var{count} comments are found as
+expected, with nothing except whitespace between them, it returns
+@code{t}; otherwise it returns @code{nil}.
+
+This function cannot tell whether the ``comments'' it traverses are
+embedded within a string. If they look like comments, it treats them
+as comments.
+@end defun
+
+To move forward over all comments and whitespace following point, use
+@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good
+argument to use, because the number of comments in the buffer cannot
+exceed that many.
-@cindex parse state
-The fifth argument @var{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
-@code{parse-partial-sexp}.
+@node Position Parse
+@subsection Finding the Parse State for a Position
+
+ For syntactic analysis, such as in indentation, often the useful
+thing is to compute the syntactic state corresponding to a given buffer
+position. This function does that conveniently.
+
+@defun syntax-ppss &optional pos
+This function returns the parser state (see next section) that the
+parser would reach at position @var{pos} starting from the beginning
+of the buffer. This is equivalent to @code{(parse-partial-sexp
+(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache
+to speed up the computation. Due to this optimization, the 2nd value
+(previous complete subexpression) and 6th value (minimum parenthesis
+depth) of the returned parser state are not meaningful.
+@end defun
+
+ @code{syntax-ppss} automatically hooks itself to
+@code{before-change-functions} to keep its cache consistent. But
+updating can fail if @code{syntax-ppss} is called while
+@code{before-change-functions} is temporarily let-bound, or if the
+buffer is modified without obeying the hook, such as when using
+@code{inhibit-modification-hooks}. For this reason, it is sometimes
+necessary to flush the cache manually.
+
+@defun syntax-ppss-flush-cache beg
+This function flushes the cache used by @code{syntax-ppss}, starting at
+position @var{beg}.
+@end defun
-The result is a list of nine elements describing the final state of
-the parse:
+ Major modes can make @code{syntax-ppss} run faster by specifying
+where it needs to start parsing.
+
+@defvar syntax-begin-function
+If this is non-@code{nil}, it should be a function that moves to an
+earlier buffer position where the parser state is equivalent to
+@code{nil}---in other words, a position outside of any comment,
+string, or parenthesis. @code{syntax-ppss} uses it to further
+optimize its computations, when the cache gives no help.
+@end defvar
+
+@node Parser State
+@subsection Parser State
+@cindex parser state
+
+ A @dfn{parser state} is a list of ten elements describing the final
+state of parsing text syntactically as part of an expression. The
+parsing functions in the following sections return a parser state as
+the value, and in some cases accept one as an argument also, so that
+you can resume parsing after it stops. Here are the meanings of the
+elements of the parser state:
@enumerate 0
-@item
-The depth in parentheses, counting from 0.
+@item
+The depth in parentheses, counting from 0. @strong{Warning:} this can
+be negative if there are more close parens than open parens between
+the start of the defun and point.
-@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, or @code{t} if a generic
string delimiter character should terminate it.
-@item
+@item
@cindex inside comment
-@code{t} if inside a comment (of either style).
+@code{t} if inside a comment (of either style),
+or the comment nesting level if inside a kind of comment
+that can be nested.
-@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
-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.
+What kind of comment is active: @code{nil} for a comment of style
+``a'' or when not inside a comment, @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}.
+
+@item
+Internal data for continuing the parsing. The meaning of this
+data is subject to change; it is used if you pass this list
+as the @var{state} argument to another call.
@end enumerate
-Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
+ Elements 1, 2, and 6 are ignored in a state which you pass as an
+argument to continue parsing, and elements 8 and 9 are used only in
+trivial cases. Those elements serve primarily to convey information
+to the Lisp program which does the parsing.
+
+ One additional piece of useful information is available from a
+parser state using this function:
-@cindex indenting with parentheses
-This function is most often used to compute indentation for languages
-that have nested parentheses.
+@defun syntax-ppss-toplevel-pos state
+This function extracts, from parser state @var{state}, the last
+position scanned in the parse which was at top level in grammatical
+structure. ``At top level'' means outside of any parentheses,
+comments, or strings.
+
+The value is @code{nil} if @var{state} represents a parse which has
+arrived at a top level position.
@end defun
-@defun scan-lists from count depth
-This function scans forward @var{count} balanced parenthetical groupings
-from position @var{from}. It returns the position where the scan stops.
-If @var{count} is negative, the scan moves backwards.
+ We have provided this access function rather than document how the
+data is represented in the state, because we plan to change the
+representation in the future.
-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
-out @var{depth} levels of parenthesis.
+@node Low-Level Parsing
+@subsection Low-Level Parsing
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
-non-@code{nil}.
+ The most basic way to use the expression parser is to tell it
+to start at a given position with a certain state, and parse up to
+a specified end position.
-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.
-@end defun
+@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
+@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 parser state
+describing the status of the parse at the point where it stops.
-@defun scan-sexps from count
-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.
+@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}.
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
-non-@code{nil}.
+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
+start of a comment. If @var{stop-comment} is the symbol
+@code{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.
-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, @code{nil} is returned.
+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. The value
+returned by a previous call to @code{parse-partial-sexp} will do
+nicely.
@end defun
-@defvar parse-sexp-ignore-comments
+@node Control Parsing
+@subsection Parameters to Control Parsing
+
+@defvar multibyte-syntax-as-symbol
+If this variable is non-@code{nil}, @code{scan-sexps} treats all
+non-@acronym{ASCII} characters as symbol constituents regardless
+of what the syntax table says about them. (However, text properties
+can still override the syntax.)
+@end defvar
+
+@defopt 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}.
+@end defopt
-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
+@vindex parse-sexp-lookup-properties
+The behavior of @code{parse-partial-sexp} is also affected by
+@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
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
-argument to use, because the number of comments in the buffer cannot
-exceed that many.
-
@node Standard Syntax Tables
@section Some Standard Syntax Tables
Lisp programs don't usually work with the elements directly; the
Lisp-level syntax table functions usually work with syntax descriptors
(@pxref{Syntax Descriptors}). Nonetheless, here we document the
-internal format.
+internal format. This format is used mostly when manipulating
+syntax properties.
Each element of a syntax table is a cons cell of the form
@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car},
This table gives the value of @var{syntax-code} which corresponds
to each syntactic type.
-@multitable @columnfractions .05 .3 .3 .3
+@multitable @columnfractions .05 .3 .3 .31
@item
@tab
@i{Integer} @i{Class}
@tab
9 @ @ escape
@tab
-14 @ @ comment-fence
+14 @ @ generic comment
@item
@tab
-15 @ string-fence
+15 @ generic string
@end multitable
For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
@tab
@samp{1} @ @ @code{(lsh 1 16)}
@tab
-@samp{3} @ @ @code{(lsh 1 18)}
+@samp{4} @ @ @code{(lsh 1 19)}
@tab
-@samp{p} @ @ @code{(lsh 1 20)}
+@samp{b} @ @ @code{(lsh 1 21)}
@item
@tab
@samp{2} @ @ @code{(lsh 1 17)}
@tab
-@samp{4} @ @ @code{(lsh 1 19)}
+@samp{p} @ @ @code{(lsh 1 20)}
@tab
-@samp{b} @ @ @code{(lsh 1 21)}
+@samp{n} @ @ @code{(lsh 1 22)}
+@item
+@tab
+@samp{3} @ @ @code{(lsh 1 18)}
@end multitable
+@defun string-to-syntax @var{desc}
+This function returns the internal form @code{(@var{syntax-code} .
+@var{matching-char})} corresponding to the syntax descriptor @var{desc}.
+@end defun
+
+@defun syntax-after pos
+This function returns the syntax code of the character in the buffer
+after position @var{pos}, taking account of syntax properties as well
+as the syntax table. If @var{pos} is outside the buffer's accessible
+portion (@pxref{Narrowing, accessible portion}), this function returns
+@code{nil}.
+@end defun
+
+@defun syntax-class syntax
+This function returns the syntax class of the syntax code
+@var{syntax}. (It masks off the high 16 bits that hold the flags
+encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it
+returns @code{nil}; this is so evaluating the expression
+
+@example
+(syntax-class (syntax-after pos))
+@end example
+
+@noindent
+where @code{pos} is outside the buffer's accessible portion, will
+yield @code{nil} without throwing errors or producing wrong syntax
+class codes.
+@end defun
+
@node Categories
@section Categories
@cindex categories of characters
+@cindex character categories
@dfn{Categories} provide an alternate way of classifying characters
syntactically. You can define several categories as needed, then
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.
+@cindex category table
Each buffer has a @dfn{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 @sc{ASCII} printing character in
+ Each category has a name, which is an @acronym{ASCII} printing character in
the range @w{@samp{ }} to @samp{~}. You specify the name of a category
when you define it with @code{define-category}.
@code{t}, that means category @var{cat} is a member of the set, and that
character @var{c} belongs to category @var{cat}.
+For the next three functions, the optional argument @var{table}
+defaults to the current buffer's category table.
+
@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.
+documentation @var{docstring}, for the category table @var{table}.
@end defun
@defun category-docstring category &optional table
@end example
@end defun
-@defun get-unused-category table
+@defun get-unused-category &optional table
This function returns a category name (a character) which is not
currently defined in @var{table}. If all possible categories are in use
-in @var{table}, it returns @code{nil},
+in @var{table}, it returns @code{nil}.
@end defun
@defun category-table
@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}
+standard category table. Otherwise, an error is signaled if @var{table}
is not a category table.
@end defun
buffer. It returns @var{table}.
@end defun
+@defun make-category-table
+This creates and returns an empty category table. In an empty category
+table, no categories have been allocated, and no characters belong to
+any categories.
+@end defun
+
@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
@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.
+This function returns the category set for character @var{char} in the
+current buffer's category table. 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)
@defun category-set-mnemonics category-set
This function converts the category set @var{category-set} into a string
-containing the names of all the categories that are members of the set.
+containing the characters that designate the categories that are members
+of the set.
@example
(category-set-mnemonics (char-category-set ?a))
But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun
+
+@deffn Command describe-categories &optional buffer-or-name
+This function describes the category specifications in the current
+category table. It inserts the descriptions in a buffer, and then
+displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it
+describes the category table of that buffer instead.
+@end deffn
+
+@ignore
+ arch-tag: 4d914e96-0283-445c-9233-75d33662908c
+@end ignore
HCoop / bpt / emacs.git / blobdiff