[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to syntax.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to syntax.texi |
|
Date: |
Thu, 06 Sep 2007 04:23:29 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:23:29
Index: syntax.texi
===================================================================
RCS file: syntax.texi
diff -N syntax.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ syntax.texi 6 Sep 2007 04:23:29 -0000 1.1
@@ -0,0 +1,1185 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
2001,
address@hidden 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation,
Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/syntax
address@hidden Syntax Tables, Abbrevs, Searching and Matching, Top
address@hidden Syntax Tables
address@hidden parsing buffer text
address@hidden syntax table
address@hidden text parsing
+
+ A @dfn{syntax table} specifies the syntactic textual function of each
+character. This information is used by the @dfn{parsing functions}, the
+complex movement commands, and others to determine where words, symbols,
+and other syntactic constructs begin and end. The current syntax table
+controls the meaning of the word motion functions (@pxref{Word Motion})
+and the list motion functions (@pxref{List Motion}), as well as the
+functions in this chapter.
+
address@hidden
+* 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.
+* Syntax Properties:: Overriding syntax with text properties.
+* 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.
+* Categories:: Another way of classifying character syntax.
address@hidden menu
+
address@hidden Syntax Basics
address@hidden Syntax Table Concepts
+
address@hidden
+ 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.
address@hidden 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
+value should be a list that encodes the syntax of the character in
+question.
+
+ Syntax tables are used only for moving across text, not for the Emacs
+Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
+expressions, and these rules cannot be changed. (Some Lisp systems
+provide ways to redefine the read syntax, but we decided to leave this
+feature out of Emacs Lisp for simplicity.)
+
+ Each buffer has its own major mode, and each major mode has its own
+idea of the syntactic class of various characters. For example, in Lisp
+mode, the character @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
+that uses that mode. Changing this table alters the syntax in all
+those buffers as well as in any buffers subsequently put in that mode.
+Occasionally several similar modes share one syntax table.
address@hidden 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
+the standard syntax table.'' Just changing the standard syntax for a
+character affects all syntax tables that inherit from it.
+
address@hidden syntax-table-p object
+This function returns @code{t} if @var{object} is a syntax table.
address@hidden defun
+
address@hidden Syntax Descriptors
address@hidden Syntax Descriptors
address@hidden syntax class
+
+ 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
address@hidden to specify the syntax you want.
+
+ The syntax table specifies a syntax class for each character. There
+is no necessary relationship between the class of a character in one
+syntax table and its class in any other table.
+
+ Each class is designated by a mnemonic character, which serves as the
+name of the class when you need to specify a class. Usually the
+designator character is one that is often assigned that class; however,
+its meaning as a designator is unvarying and independent of what syntax
+that character currently has. Thus, @samp{\} as a designator character
+always gives ``escape character'' syntax, regardless of what syntax
address@hidden currently has.
+
address@hidden syntax descriptor
+ A syntax descriptor is a Lisp string that specifies a syntax class, a
+matching character (used only for the parenthesis classes) and flags.
+The first character is the designator for a syntax class. The second
+character is the character to match; if it is unused, put a space there.
+Then come the characters for any desired flags. If no matching
+character or flags are needed, one character is sufficient.
+
+ For example, the syntax descriptor for the character @samp{*} in C
+mode is @address@hidden 23}} (i.e., punctuation, matching character slot
+unused, second character of a comment-starter, first character of a
+comment-ender), and the entry for @samp{/} is @address@hidden 14}} (i.e.,
+punctuation, matching character slot unused, first character of a
+comment-starter, second character of a comment-ender).
+
address@hidden
+* Syntax Class Table:: Table of syntax classes.
+* Syntax Flags:: Additional flags each character can have.
address@hidden menu
+
address@hidden Syntax Class Table
address@hidden Table of Syntax Classes
+
+ Here is a table of syntax classes, the characters that stand for them,
+their meanings, and examples of their use.
+
address@hidden {Syntax class} @w{whitespace character}
address@hidden characters} (designated by @address@hidden@ }} or @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 classified as whitespace in almost all major
+modes.
address@hidden deffn
+
address@hidden {Syntax class} @w{word constituent}
address@hidden 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.
address@hidden deffn
+
address@hidden {Syntax class} @w{symbol constituent}
address@hidden constituents} (designated by @samp{_}) are the extra
+characters that are used in variable and command names along with word
+constituents. For example, the symbol constituents class is used in
+Lisp mode to indicate that certain characters may be part of symbol
+names even though they are not part of English words. These characters
+are @samp{$&*+-_<>}. In standard C, the only non-word-constituent
+character that is valid in symbols is underscore (@samp{_}).
address@hidden deffn
+
address@hidden {Syntax class} @w{punctuation character}
address@hidden 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.
+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. Other programming language modes,
+such as C mode, use punctuation syntax for operators.
address@hidden deffn
+
address@hidden {Syntax class} @w{open parenthesis character}
address@hidden {Syntax class} @w{close parenthesis character}
address@hidden 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.
address@hidden
+
+The class of open parentheses is designated by @samp{(}, and that of
+close parentheses by @samp{)}.
+
+In English text, and in C code, the parenthesis pairs are @samp{()},
address@hidden, and @address@hidden@}}. In Emacs Lisp, the delimiters for
lists and
+vectors (@samp{()} and @samp{[]}) are classified as parenthesis
+characters.
address@hidden deffn
+
address@hidden {Syntax class} @w{string quote}
address@hidden quote characters} (designated by @samp{"}) are used in
+many languages, including Lisp and C, to delimit string constants. The
+same string quote character appears at the beginning and the end of a
+string. Such quoted strings do not nest.
+
+The parsing facilities of 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.
address@hidden deffn
+
address@hidden {Syntax class} @w{escape-syntax character}
+An @dfn{escape character} (designated by @samp{\}) starts an escape
+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
address@hidden is address@hidden @xref{Word Motion}.
address@hidden deffn
+
address@hidden {Syntax class} @w{character quote}
+A @dfn{character quote character} (designated by @samp{/}) quotes the
+following character so that it loses its normal syntactic meaning. This
+differs from an escape character in that only the character immediately
+following is ever affected.
+
+Characters in this class count as part of words if
address@hidden is address@hidden @xref{Word Motion}.
+
+This class is used for backslash in @TeX{} mode.
address@hidden deffn
+
address@hidden {Syntax class} @w{paired delimiter}
address@hidden delimiter characters} (designated by @samp{$}) are like
+string quote characters except that the syntactic properties of the
+characters between the delimiters are not suppressed. Only @TeX{} mode
+uses a paired delimiter presently---the @samp{$} that both enters and
+leaves math mode.
address@hidden deffn
+
address@hidden {Syntax class} @w{expression prefix}
+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).
address@hidden deffn
+
address@hidden {Syntax class} @w{comment starter}
address@hidden {Syntax class} @w{comment ender}
address@hidden comment syntax
+The @dfn{comment starter} and @dfn{comment ender} characters are used in
+various languages to delimit comments. These classes are designated
+by @samp{<} and @samp{>}, respectively.
+
+English text has no comment characters. In Lisp, the semicolon
+(@samp{;}) starts a comment and a newline or formfeed ends one.
address@hidden deffn
+
address@hidden {Syntax class} @w{inherit standard syntax}
+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 class is @samp{@@}.
address@hidden deffn
+
address@hidden {Syntax class} @w{generic comment delimiter}
+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
address@hidden 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.
address@hidden deffn
+
address@hidden {Syntax class} @w{generic string delimiter}
+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
address@hidden 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.
address@hidden deffn
+
address@hidden Syntax Flags
address@hidden Syntax Flags
address@hidden syntax flags
+
+ In addition to the classes, entries for characters in a syntax table
+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{/*}),
address@hidden 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:
+
address@hidden @bullet
address@hidden
address@hidden means @var{c} is the start of a two-character comment-start
+sequence.
+
address@hidden
address@hidden means @var{c} is the second character of such a sequence.
+
address@hidden
address@hidden means @var{c} is the start of a two-character comment-end
+sequence.
+
address@hidden
address@hidden means @var{c} is the second character of such a sequence.
+
address@hidden
address@hidden Emacs 19 feature
address@hidden 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
+``b''-style comment-start sequence with the @samp{b} flag.
+
+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:
+
address@hidden @asis
address@hidden @samp{/}
address@hidden
address@hidden @samp{*}
address@hidden
address@hidden newline
address@hidden>b}
address@hidden table
+
+This defines four comment-delimiting sequences:
+
address@hidden @asis
address@hidden @samp{/*}
+This is a comment-start sequence for ``a'' style because the
+second character, @samp{*}, does not have the @samp{b} flag.
+
address@hidden @samp{//}
+This is a comment-start sequence for ``b'' style because the second
+character, @samp{/}, does have the @samp{b} flag.
+
address@hidden @samp{*/}
+This is a comment-end sequence for ``a'' style because the first
+character, @samp{*}, does not have the @samp{b} flag.
+
address@hidden newline
+This is a comment-end sequence for ``b'' style, because the newline
+character has the @samp{b} flag.
address@hidden table
+
address@hidden
address@hidden 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.
+
address@hidden
address@hidden Emacs 19 feature
address@hidden 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 classes.
+
+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}.
address@hidden itemize
+
address@hidden Syntax Table Functions
address@hidden Syntax Table Functions
+
+ In this section we describe functions for creating, accessing and
+altering syntax tables.
+
address@hidden make-syntax-table &optional table
+This function creates a new syntax table, with all values initialized
+to @code{nil}. If @var{table} is address@hidden, 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.
address@hidden defun
+
address@hidden copy-syntax-table &optional table
+This function constructs a copy of @var{table} and returns it. If
address@hidden is not supplied (or is @code{nil}), it returns a copy of the
+standard syntax table. Otherwise, an error is signaled if @var{table} is
+not a syntax table.
address@hidden defun
+
address@hidden Command modify-syntax-entry char syntax-descriptor &optional
table
+This function sets the syntax entry for @var{char} according to
address@hidden 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 seventeen syntax class designator characters. An error is also
+signaled if @var{char} is not a character.
+
address@hidden
address@hidden
address@hidden @r{Examples:}
+
+;; @r{Put the space character in class whitespace.}
+(modify-syntax-entry ?\s " ")
+ @result{} nil
address@hidden group
+
address@hidden
+;; @r{Make @samp{$} an open parenthesis character,}
+;; @r{with @samp{^} as its matching close.}
+(modify-syntax-entry ?$ "(^")
+ @result{} nil
address@hidden group
+
address@hidden
+;; @r{Make @samp{^} a close parenthesis character,}
+;; @r{with @samp{$} as its matching open.}
+(modify-syntax-entry ?^ ")$")
+ @result{} nil
address@hidden group
+
address@hidden
+;; @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.}
+(modify-syntax-entry ?/ ". 14")
+ @result{} nil
address@hidden group
address@hidden example
address@hidden deffn
+
address@hidden char-syntax character
+This function returns the syntax class of @var{character}, represented
+by its mnemonic designator character. This returns @emph{only} the
+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
+does not show the fact that it is also part of comment-start and -end
+sequences. The third example shows that open parenthesis is in the class
+of open parentheses. This does not show the fact that it has a matching
+character, @samp{)}.
+
address@hidden
address@hidden
+(string (char-syntax ?\s))
+ @result{} " "
address@hidden group
+
address@hidden
+(string (char-syntax ?/))
+ @result{} "."
address@hidden group
+
address@hidden
+(string (char-syntax ?\())
+ @result{} "("
address@hidden group
address@hidden example
+
+We use @code{string} to make it easier to see the character returned by
address@hidden
address@hidden defun
+
address@hidden set-syntax-table table
+This function makes @var{table} the syntax table for the current buffer.
+It returns @var{table}.
address@hidden defun
+
address@hidden syntax-table
+This function returns the current syntax table, which is the table for
+the current buffer.
address@hidden defun
+
address@hidden with-syntax-table @var{table} @address@hidden
+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.
address@hidden defmac
+
address@hidden Syntax Properties
address@hidden Syntax Properties
address@hidden 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}. You can use Font Lock mode to set
address@hidden text properties. @xref{Setting Syntax
+Properties}.
+
+The valid values of @code{syntax-table} text property are:
+
address@hidden @asis
address@hidden @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.
+
address@hidden @code{(@var{syntax-code} . @var{matching-char})}
+A cons cell of this format specifies the syntax for this
+occurrence of the character. (@pxref{Syntax Table Internals})
+
address@hidden @code{nil}
+If the property is @code{nil}, the character's syntax is determined from
+the current syntax table in the usual way.
address@hidden table
+
address@hidden parse-sexp-lookup-properties
+If this is address@hidden, the syntax scanning functions pay attention
+to syntax text properties. Otherwise they use only the current syntax
+table.
address@hidden defvar
+
address@hidden Motion and Syntax
address@hidden Motion and Syntax
+
+ This section describes functions for moving across characters that
+have certain syntax classes.
+
address@hidden skip-syntax-forward syntaxes &optional limit
+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.
address@hidden defun
+
address@hidden 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.
+
+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.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden Parsing Expressions
address@hidden 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.
+
+ 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),
+
address@hidden
+(put-text-property 1 9 'syntax-table '(15 . nil))
address@hidden example
+
address@hidden
+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.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Motion via Parsing
address@hidden Motion Commands Based on Parsing
+
+ This section describes simple point-motion functions that operate
+based on parsing expressions.
+
address@hidden 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
address@hidden
+
+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.
address@hidden defun
+
address@hidden 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
address@hidden
+
+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.
address@hidden defun
+
address@hidden 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
address@hidden; 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.
address@hidden defun
+
+To move forward over all comments and whitespace following point, use
address@hidden(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.
+
address@hidden Position Parse
address@hidden 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.
+
address@hidden 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.
address@hidden defun
+
+ @code{syntax-ppss} automatically hooks itself to
address@hidden to keep its cache consistent. But
+updating can fail if @code{syntax-ppss} is called while
address@hidden is temporarily let-bound, or if the
+buffer is modified without obeying the hook, such as when using
address@hidden For this reason, it is sometimes
+necessary to flush the cache manually.
+
address@hidden syntax-ppss-flush-cache beg
+This function flushes the cache used by @code{syntax-ppss}, starting at
+position @var{beg}.
address@hidden defun
+
+ Major modes can make @code{syntax-ppss} run faster by specifying
+where it needs to start parsing.
+
address@hidden syntax-begin-function
+If this is address@hidden, it should be a function that moves to an
+earlier buffer position where the parser state is equivalent to
address@hidden 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.
address@hidden defvar
+
address@hidden Parser State
address@hidden Parser State
address@hidden 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:
+
address@hidden 0
address@hidden
+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.
+
address@hidden
address@hidden innermost containing parentheses
+The character position of the start of the innermost parenthetical
+grouping containing the stopping point; @code{nil} if none.
+
address@hidden
address@hidden previous complete subexpression
+The character position of the start of the last complete subexpression
+terminated; @code{nil} if none.
+
address@hidden
address@hidden inside string
address@hidden 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.
+
address@hidden
address@hidden inside comment
address@hidden if inside a comment (of either style),
+or the comment nesting level if inside a kind of comment
+that can be nested.
+
address@hidden
address@hidden quote character
address@hidden if point is just after a quote character.
+
address@hidden
+The minimum parenthesis depth encountered during this scan.
+
address@hidden
+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.
+
address@hidden
+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}.
+
address@hidden
+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.
address@hidden enumerate
+
+ 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:
+
address@hidden 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.
address@hidden defun
+
+ 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.
+
address@hidden Low-Level Parsing
address@hidden Low-Level Parsing
+
+ 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.
+
address@hidden parse-partial-sexp start limit &optional target-depth
stop-before state stop-comment
+This function parses a sexp in the current buffer starting at
address@hidden, not scanning past @var{limit}. It stops at position
address@hidden 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.
+
address@hidden parenthesis depth
+If the third argument @var{target-depth} is address@hidden, 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 address@hidden, parsing
+stops when it comes to any character that starts a sexp. If
address@hidden is address@hidden, parsing stops when it comes to the
+start of a comment. If @var{stop-comment} is the symbol
address@hidden, parsing stops after the start of a comment or a
+string, or the end of a comment or a string, whichever comes first.
+
+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.
address@hidden defun
+
address@hidden Control Parsing
address@hidden Parameters to Control Parsing
+
address@hidden multibyte-syntax-as-symbol
+If this variable is address@hidden, @code{scan-sexps} treats all
address@hidden characters as symbol constituents regardless
+of what the syntax table says about them. (However, text properties
+can still override the syntax.)
address@hidden defvar
+
address@hidden parse-sexp-ignore-comments
address@hidden skipping comments
+If the value is address@hidden, then comments are treated as
+whitespace by the functions in this section and by @code{forward-sexp},
address@hidden and @code{scan-sexps}.
address@hidden defopt
+
address@hidden parse-sexp-lookup-properties
+The behavior of @code{parse-partial-sexp} is also affected by
address@hidden (@pxref{Syntax Properties}).
+
+You can use @code{forward-comment} to move forward or backward over
+one comment or several comments.
+
address@hidden Standard Syntax Tables
address@hidden Some Standard Syntax Tables
+
+ Most of the major modes in Emacs have their own syntax tables. Here
+are several of them:
+
address@hidden standard-syntax-table
+This function returns the standard syntax table, which is the syntax
+table used in Fundamental mode.
address@hidden defun
+
address@hidden text-mode-syntax-table
+The value of this variable is the syntax table used in Text mode.
address@hidden defvar
+
address@hidden c-mode-syntax-table
+The value of this variable is the syntax table for C-mode buffers.
address@hidden defvar
+
address@hidden 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.)
address@hidden defvar
+
address@hidden Syntax Table Internals
address@hidden Syntax Table Internals
address@hidden syntax table internals
+
+ 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. This format is used mostly when manipulating
+syntax properties.
+
+ Each element of a syntax table is a cons cell of the form
address@hidden(@var{syntax-code} . @var{matching-char})}. The @sc{car},
address@hidden, is an integer that encodes the syntax class, and any
+flags. The @sc{cdr}, @var{matching-char}, is address@hidden if
+a character to match was specified.
+
+ This table gives the value of @var{syntax-code} which corresponds
+to each syntactic type.
+
address@hidden @columnfractions .05 .3 .3 .31
address@hidden
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden
+0 @ @ whitespace
address@hidden
+5 @ @ close parenthesis
address@hidden
+10 @ @ character quote
address@hidden
address@hidden
+1 @ @ punctuation
address@hidden
+6 @ @ expression prefix
address@hidden
+11 @ @ comment-start
address@hidden
address@hidden
+2 @ @ word
address@hidden
+7 @ @ string quote
address@hidden
+12 @ @ comment-end
address@hidden
address@hidden
+3 @ @ symbol
address@hidden
+8 @ @ paired delimiter
address@hidden
+13 @ @ inherit
address@hidden
address@hidden
+4 @ @ open parenthesis
address@hidden
+9 @ @ escape
address@hidden
+14 @ @ generic comment
address@hidden
address@hidden
+15 @ generic string
address@hidden multitable
+
+ 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.
+
address@hidden @columnfractions .05 .3 .3 .3
address@hidden
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden
address@hidden @ @ @code{(lsh 1 16)}
address@hidden
address@hidden @ @ @code{(lsh 1 19)}
address@hidden
address@hidden @ @ @code{(lsh 1 21)}
address@hidden
address@hidden
address@hidden @ @ @code{(lsh 1 17)}
address@hidden
address@hidden @ @ @code{(lsh 1 20)}
address@hidden
address@hidden @ @ @code{(lsh 1 22)}
address@hidden
address@hidden
address@hidden @ @ @code{(lsh 1 18)}
address@hidden multitable
+
address@hidden string-to-syntax @var{desc}
+This function returns the internal form corresponding to the syntax
+descriptor @var{desc}, a cons cell @code{(@var{syntax-code}
+. @var{matching-char})}.
address@hidden defun
+
address@hidden 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
address@hidden
address@hidden defun
+
address@hidden syntax-class syntax
+This function returns the syntax class of the syntax code
address@hidden (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
+
address@hidden
+(syntax-class (syntax-after pos))
address@hidden example
+
address@hidden
+where @code{pos} is outside the buffer's accessible portion, will
+yield @code{nil} without throwing errors or producing wrong syntax
+class codes.
address@hidden defun
+
address@hidden Categories
address@hidden Categories
address@hidden categories of characters
address@hidden character categories
+
+ @dfn{Categories} provide an alternate way of classifying characters
+syntactically. You can define several categories as needed, then
+independently assign each character to one or more categories. Unlike
+syntax classes, categories are not mutually exclusive; it is normal for
+one character to belong to several categories.
+
address@hidden 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 @acronym{ASCII} printing character in
+the range @address@hidden }} to @samp{~}. You specify the name of a category
+when you define it with @code{define-category}.
+
+ 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
address@hidden, 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.
+
address@hidden define-category char docstring &optional table
+This function defines a new category, with name @var{char} and
+documentation @var{docstring}, for the category table @var{table}.
address@hidden defun
+
address@hidden category-docstring category &optional table
+This function returns the documentation string of category @var{category}
+in category table @var{table}.
+
address@hidden
+(category-docstring ?a)
+ @result{} "ASCII"
+(category-docstring ?l)
+ @result{} "Latin"
address@hidden example
address@hidden defun
+
address@hidden 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}.
address@hidden defun
+
address@hidden category-table
+This function returns the current buffer's category table.
address@hidden defun
+
address@hidden category-table-p object
+This function returns @code{t} if @var{object} is a category table,
+otherwise @code{nil}.
address@hidden defun
+
address@hidden standard-category-table
+This function returns the standard category table.
address@hidden defun
+
address@hidden copy-category-table &optional table
+This function constructs a copy of @var{table} and returns it. If
address@hidden is not supplied (or is @code{nil}), it returns a copy of the
+standard category table. Otherwise, an error is signaled if @var{table}
+is not a category table.
address@hidden defun
+
address@hidden set-category-table table
+This function makes @var{table} the category table for the current
+buffer. It returns @var{table}.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden 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.
+
address@hidden
+(make-category-set "al")
+ @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
address@hidden example
address@hidden defun
+
address@hidden char-category-set char
+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.
+
address@hidden
+(char-category-set ?a)
+ @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
address@hidden example
address@hidden defun
+
address@hidden category-set-mnemonics category-set
+This function converts the category set @var{category-set} into a string
+containing the characters that designate the categories that are members
+of the set.
+
address@hidden
+(category-set-mnemonics (char-category-set ?a))
+ @result{} "al"
address@hidden example
address@hidden defun
+
address@hidden 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 address@hidden, then it deletes @var{category}
+instead.
address@hidden defun
+
address@hidden 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 address@hidden, it
+describes the category table of that buffer instead.
address@hidden deffn
+
address@hidden
+ arch-tag: 4d914e96-0283-445c-9233-75d33662908c
address@hidden ignore