[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:14:37 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:14:36
Index: syntax.texi
===================================================================
RCS file: syntax.texi
diff -N syntax.texi
--- syntax.texi 11 Apr 2007 16:27:33 -0000 1.59
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1185 +0,0 @@
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
- [Emacs-diffs] Changes to syntax.texi,
Glenn Morris <=