Merged in changes from CVS trunk.
Patches applied:
* miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-325
Update from CVS
* miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-326
Update from CVS
* miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-327
Update from CVS
* miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-328
Update from CVS: src/.gdbinit (xsymbol): Fix last change.
* miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-329
Update from CVS
git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-166
@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999@c Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/syntax@node Syntax Tables, Abbrevs, Searching and Matching, Top@chapter Syntax Tables@cindex parsing@cindex syntax table@cindex text parsing A @dfn{syntax table} specifies the syntactic textual function of eachcharacter. This information is used by the @dfn{parsing functions}, thecomplex movement commands, and others to determine where words, symbols,and other syntactic constructs begin and end. The current syntax tablecontrols the meaning of the word motion functions (@pxref{Word Motion})and the list motion functions (@pxref{List Motion}), as well as thefunctions in this chapter.@menu* Basics: Syntax Basics. Basic concepts of syntax tables.* Desc: Syntax Descriptors. How characters are classified.* Syntax Table Functions:: How to create, examine and alter syntax tables.* 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.@end menu@node Syntax Basics@section Syntax Table Concepts@ifnottex A @dfn{syntax table} provides Emacs with the information thatdetermines the syntactic use of each character in a buffer. Thisinformation is used by the parsing commands, the complex movementcommands, and others to determine where words, symbols, and othersyntactic constructs begin and end. The current syntax table controlsthe meaning of the word motion functions (@pxref{Word Motion}) and thelist motion functions (@pxref{List Motion}) as well as the functions inthis chapter.@end ifnottex A syntax table is a char-table (@pxref{Char-Tables}). The element atindex @var{c} describes the character with code @var{c}. The element'svalue should be a list that encodes the syntax of the character inquestion. Syntax tables are used only for moving across text, not for the EmacsLisp reader. Emacs Lisp uses built-in syntactic rules when reading Lispexpressions, and these rules cannot be changed. (Some Lisp systemsprovide ways to redefine the read syntax, but we decided to leave thisfeature out of Emacs Lisp for simplicity.) Each buffer has its own major mode, and each major mode has its ownidea of the syntactic class of various characters. For example, in Lispmode, the character @samp{;} begins a comment, but in C mode, itterminates a statement. To support these variations, Emacs makes thechoice of syntax table local to each buffer. Typically, each majormode has its own syntax table and installs that table in each bufferthat uses that mode. Changing this table alters the syntax in allthose buffers as well as in any buffers subsequently put in that mode.Occasionally several similar modes share one syntax table.@xref{Example Major Modes}, for an example of how to set up a syntaxtable.A syntax table can inherit the data for some characters from thestandard syntax table, while specifying other characters itself. The``inherit'' syntax class means ``inherit this character's syntax fromthe standard syntax table.'' Just changing the standard syntax for acharacter affects all syntax tables that inherit from it.@defun syntax-table-p objectThis function returns @code{t} if @var{object} is a syntax table.@end defun@node Syntax Descriptors@section Syntax Descriptors@cindex syntax classes This section describes the syntax classes and flags that denote thesyntax of a character, and how they are represented as a @dfn{syntaxdescriptor}, which is a Lisp string that you pass to@code{modify-syntax-entry} to specify the syntax you want. The syntax table specifies a syntax class for each character. Thereis no necessary relationship between the class of a character in onesyntax table and its class in any other table. Each class is designated by a mnemonic character, which serves as thename of the class when you need to specify a class. Usually thedesignator character is one that is often assigned that class; however,its meaning as a designator is unvarying and independent of what syntaxthat character currently has. Thus, @samp{\} as a designator characteralways gives ``escape character'' syntax, regardless of what syntax@samp{\} currently has.@cindex syntax descriptor A syntax descriptor is a Lisp string that specifies a syntax class, amatching character (used only for the parenthesis classes) and flags.The first character is the designator for a syntax class. The secondcharacter is the character to match; if it is unused, put a space there.Then come the characters for any desired flags. If no matchingcharacter or flags are needed, one character is sufficient. For example, the syntax descriptor for the character @samp{*} in Cmode is @samp{@w{. 23}} (i.e., punctuation, matching character slotunused, second character of a comment-starter, first character of acomment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,punctuation, matching character slot unused, first character of acomment-starter, second character of a comment-ender).@menu* Syntax Class Table:: Table of syntax classes.* Syntax Flags:: Additional flags each character can have.@end menu@node Syntax Class Table@subsection Table of Syntax Classes Here is a table of syntax classes, the characters that stand for them,their meanings, and examples of their use.@deffn {Syntax class} @w{whitespace character}@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})separate symbols and words from each other. Typically, whitespacecharacters have no other syntactic significance, and multiple whitespacecharacters are syntactically equivalent to a single one. Space, tab,newline and formfeed are classified as whitespace in almost all majormodes.@end deffn@deffn {Syntax class} @w{word constituent}@dfn{Word constituents} (designated by @samp{w}) are parts of normalEnglish words and are typically used in variable and command names inprograms. All upper- and lower-case letters, and the digits, are typicallyword constituents.@end deffn@deffn {Syntax class} @w{symbol constituent}@dfn{Symbol constituents} (designated by @samp{_}) are the extracharacters that are used in variable and command names along with wordconstituents. For example, the symbol constituents class is used inLisp mode to indicate that certain characters may be part of symbolnames even though they are not part of English words. These charactersare @samp{$&*+-_<>}. In standard C, the only non-word-constituentcharacter that is valid in symbols is underscore (@samp{_}).@end deffn@deffn {Syntax class} @w{punctuation character}@dfn{Punctuation characters} (designated by @samp{.}) are thosecharacters that are used as punctuation in English, or are used in someway in a programming language to separate symbols from one another.Most programming language modes, including Emacs Lisp mode, have nocharacters in this class since the few characters that are not symbol orword constituents all have other uses.@end deffn@deffn {Syntax class} @w{open parenthesis character}@deffnx {Syntax class} @w{close parenthesis character}@cindex parenthesis syntaxOpen and close @dfn{parenthesis characters} are characters used indissimilar pairs to surround sentences or expressions. Such a groupingis begun with an open parenthesis character and terminated with a close.Each open parenthesis character matches a particular close parenthesischaracter, and vice versa. Normally, Emacs indicates momentarily thematching open parenthesis when you insert a close parenthesis.@xref{Blinking}.The class of open parentheses is designated by @samp{(}, and that ofclose parentheses by @samp{)}.In English text, and in C code, the parenthesis pairs are @samp{()},@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists andvectors (@samp{()} and @samp{[]}) are classified as parenthesischaracters.@end deffn@deffn {Syntax class} @w{string quote}@dfn{String quote characters} (designated by @samp{"}) are used inmany languages, including Lisp and C, to delimit string constants. Thesame string quote character appears at the beginning and the end of astring. 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 aresuppressed.The Lisp modes have two string quote characters: double-quote (@samp{"})and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but itis used in Common Lisp. C also has two string quote characters:double-quote for strings, and single-quote (@samp{'}) for characterconstants.English text has no string quote characters because English is not aprogramming language. Although quotation marks are used in English,we do not want them to turn off the usual syntactic properties ofother characters in the quotation.@end deffn@deffn {Syntax class} @w{escape}An @dfn{escape character} (designated by @samp{\}) starts an escapesequence such as is used in C string and character constants. Thecharacter @samp{\} belongs to this class in both C and Lisp. (In C, itis used thus only inside strings, but it turns out to cause no troubleto treat it this way throughout C code.)Characters in this class count as part of words if@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.@end deffn@deffn {Syntax class} @w{character quote}A @dfn{character quote character} (designated by @samp{/}) quotes thefollowing character so that it loses its normal syntactic meaning. Thisdiffers from an escape character in that only the character immediatelyfollowing is ever affected.Characters in this class count as part of words if@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.This class is used for backslash in @TeX{} mode.@end deffn@deffn {Syntax class} @w{paired delimiter}@dfn{Paired delimiter characters} (designated by @samp{$}) are likestring quote characters except that the syntactic properties of thecharacters between the delimiters are not suppressed. Only @TeX{} modeuses a paired delimiter presently---the @samp{$} that both enters andleaves math mode.@end deffn@deffn {Syntax class} @w{expression prefix}An @dfn{expression prefix operator} (designated by @samp{'}) is used forsyntactic operators that are considered as part of an expression if theyappear next to one. In Lisp modes, these characters include theapostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used inmacros), and @samp{#} (used in the read syntax for certain data types).@end deffn@deffn {Syntax class} @w{comment starter}@deffnx {Syntax class} @w{comment ender}@cindex comment syntaxThe @dfn{comment starter} and @dfn{comment ender} characters are used invarious languages to delimit comments. These classes are designatedby @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.@end deffn@deffn {Syntax class} @w{inherit}This syntax class does not specify a particular syntax. It says to lookin the standard syntax table to find the syntax of this character. Thedesignator for this syntax code is @samp{@@}.@end deffn@deffn {Syntax class} @w{generic comment delimiter}A @dfn{generic comment delimiter} (designated by @samp{!}) startsor ends a special kind of comment. @emph{Any} generic comment delimitermatches @emph{any} generic comment delimiter, but they cannot matcha comment starter or comment ender; generic comment delimiters can onlymatch each other.This syntax class is primarily meant for use with the@code{syntax-table} text property (@pxref{Syntax Properties}). You canmark any range of characters as forming a comment, by giving the firstand last characters of the range @code{syntax-table} propertiesidentifying them as generic comment delimiters.@end deffn@deffn {Syntax class} @w{generic string delimiter}A @dfn{generic string delimiter} (designated by @samp{|}) starts or endsa string. This class differs from the string quote class in that @emph{any}generic string delimiter can match any other generic string delimiter; butthey do not match ordinary string quote characters.This syntax class is primarily meant for use with the@code{syntax-table} text property (@pxref{Syntax Properties}). You canmark any range of characters as forming a string constant, by giving thefirst and last characters of the range @code{syntax-table} propertiesidentifying them as generic string delimiters.@end deffn@node Syntax Flags@subsection Syntax Flags@cindex syntax flags In addition to the classes, entries for characters in a syntax tablecan specify flags. There are seven possible flags, represented by thecharacters @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 describemulti-character comment delimiters. The digit flags indicate that acharacter can @emph{also} be part of a comment sequence, in addition tothe syntactic properties associated with its character class. The flagsare independent of the class and each other for the sake of characterssuch as @samp{*} in C mode, which is a punctuation character, @emph{and}the second character of a start-of-comment sequence (@samp{/*}),@emph{and} the first character of an end-of-comment sequence(@samp{*/}). Here is a table of the possible flags for a character @var{c},and what they mean:@itemize @bullet@item@samp{1} means @var{c} is the start of a two-character comment-startsequence.@item@samp{2} means @var{c} is the second character of such a sequence.@item@samp{3} means @var{c} is the start of a two-character comment-endsequence.@item@samp{4} means @var{c} is the second character of such a sequence.@item@c Emacs 19 feature@samp{b} means that @var{c} as a comment delimiter belongs to thealternative ``b'' comment style.Emacs supports two comment styles simultaneously in any one syntaxtable. This is for the sake of C++. Each style of comment syntax hasits own comment-start sequence and its own comment-end sequence. Eachcomment must stick to one style or the other; thus, if it starts withthe comment-start sequence of style ``b'', it must also end with thecomment-end sequence of style ``b''.The two comment-start sequences must begin with the same character; onlythe 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, itapplies to the ``a'' style.The appropriate comment syntax settings for C++ are as follows:@table @asis@item @samp{/}@samp{124b}@item @samp{*}@samp{23}@item newline@samp{>b}@end tableThis defines four comment-delimiting sequences:@table @asis@item @samp{/*}This is a comment-start sequence for ``a'' style because thesecond character, @samp{*}, does not have the @samp{b} flag.@item @samp{//}This is a comment-start sequence for ``b'' style because the secondcharacter, @samp{/}, does have the @samp{b} flag.@item @samp{*/}This is a comment-end sequence for ``a'' style because the firstcharacter, @samp{*}, does not have the @samp{b} flag.@item newlineThis is a comment-end sequence for ``b'' style, because the newlinecharacter has the @samp{b} flag.@end table@item@samp{n} on a comment delimiter character specifiesthat this kind of comment can be nested. For a two-charactercomment delimiter, @samp{n} on either character makes itnestable.@item@c Emacs 19 feature@samp{p} identifies an additional ``prefix character'' for Lisp syntax.These characters are treated as whitespace when they appear betweenexpressions. When they appear within an expression, they are handledaccording to their usual syntax codes.The function @code{backward-prefix-chars} moves back over thesecharacters, as well as over characters whose primary syntax class isprefix (@samp{'}). @xref{Motion and Syntax}.@end itemize@node Syntax Table Functions@section Syntax Table Functions In this section we describe functions for creating, accessing andaltering syntax tables.@defun make-syntax-table &optional tableThis function creates a new syntax table, with all values initializedto @code{nil}. If @var{table} is non-@code{nil}, it becomes theparent of the new syntax table, otherwise the standard syntax table isthe parent. Like all char-tables, a syntax table inherits from itsparent. Thus the original syntax of all characters in the returnedsyntax table is determined by the parent. @xref{Char-Tables}.Most major mode syntax tables are created in this way.@end defun@defun copy-syntax-table &optional tableThis function constructs a copy of @var{table} and returns it. If@var{table} is not supplied (or is @code{nil}), it returns a copy of thestandard syntax table. Otherwise, an error is signaled if @var{table} isnot a syntax table.@end defun@deffn Command modify-syntax-entry char syntax-descriptor &optional tableThis function sets the syntax entry for @var{char} according to@var{syntax-descriptor}. The syntax is changed only for @var{table},which defaults to the current buffer's syntax table, and not in anyother syntax table. The argument @var{syntax-descriptor} specifies thedesired syntax; this is a string beginning with a class designatorcharacter, and optionally containing a matching character and flags aswell. @xref{Syntax Descriptors}.This function always returns @code{nil}. The old syntax information inthe table for this character is discarded.An error is signaled if the first character of the syntax descriptor is notone of the seventeen syntax class designator characters. An error is alsosignaled if @var{char} is not a character.@example@group@exdent @r{Examples:};; @r{Put the space character in class whitespace.}(modify-syntax-entry ?\s " ") @result{} nil@end group@group;; @r{Make @samp{$} an open parenthesis character,};; @r{with @samp{^} as its matching close.}(modify-syntax-entry ?$ "(^") @result{} nil@end group@group;; @r{Make @samp{^} a close parenthesis character,};; @r{with @samp{$} as its matching open.}(modify-syntax-entry ?^ ")$") @result{} nil@end group@group;; @r{Make @samp{/} a punctuation character,};; @r{the first character of a start-comment sequence,};; @r{and the second character of an end-comment sequence.};; @r{This is used in C mode.}(modify-syntax-entry ?/ ". 14") @result{} nil@end group@end example@end deffn@defun char-syntax characterThis function returns the syntax class of @var{character}, representedby its mnemonic designator character. This returns @emph{only} theclass, 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 thatthe syntax class of space is whitespace (represented by a space). Thesecond example shows that the syntax of @samp{/} is punctuation. Thisdoes not show the fact that it is also part of comment-start and -endsequences. The third example shows that open parenthesis is in the classof open parentheses. This does not show the fact that it has a matchingcharacter, @samp{)}.@example@group(string (char-syntax ?\s)) @result{} " "@end group@group(string (char-syntax ?/)) @result{} "."@end group@group(string (char-syntax ?\()) @result{} "("@end group@end exampleWe use @code{string} to make it easier to see the character returned by@code{char-syntax}.@end defun@defun set-syntax-table tableThis function makes @var{table} the syntax table for the current buffer.It returns @var{table}.@end defun@defun syntax-tableThis function returns the current syntax table, which is the table forthe current buffer.@end defun@defmac with-syntax-table @var{table} @var{body}...@tindex with-syntax-tableThis macro executes @var{body} using @var{table} as the current syntaxtable. It returns the value of the last form in @var{body}, afterrestoring the old current syntax table.Since each buffer has its own current syntax table, we should make thatmore precise: @code{with-syntax-table} temporarily alters the currentsyntax table of whichever buffer is current at the time the macroexecution starts. Other buffers are not affected.@end defmac@node Syntax Properties@section Syntax Properties@kindex syntax-table @r{(text property)}When the syntax table is not flexible enough to specify the syntax of alanguage, you can use @code{syntax-table} text properties to overridethe syntax table for specific character occurrences in the buffer.@xref{Text Properties}.The valid values of @code{syntax-table} text property are:@table @asis@item @var{syntax-table}If the property value is a syntax table, that table is used instead ofthe current buffer's syntax table to determine the syntax for thisoccurrence of the character.@item @code{(@var{syntax-code} . @var{matching-char})}A cons cell of this format specifies the syntax for thisoccurrence of the character. (@pxref{Syntax Table Internals})@item @code{nil}If the property is @code{nil}, the character's syntax is determined fromthe current syntax table in the usual way.@end table@defvar parse-sexp-lookup-propertiesIf this is non-@code{nil}, the syntax scanning functions pay attentionto syntax text properties. Otherwise they use only the current syntaxtable.@end defvar@node Motion and Syntax@section Motion and Syntax This section describes functions for moving across characters thathave certain syntax classes.@defun skip-syntax-forward syntaxes &optional limitThis function moves point forward across characters having syntaxclasses mentioned in @var{syntaxes} (a string of syntax codecharacters). It stops when it encounters the end of the buffer, orposition @var{limit} (if specified), or a character it is not supposedto skip.If @var{syntaxes} starts with @samp{^}, then the function skipscharacters whose syntax is @emph{not} in @var{syntaxes}.The return value is the distance traveled, which is a nonnegativeinteger.@end defun@defun skip-syntax-backward syntaxes &optional limitThis function moves point backward across characters whose syntaxclasses are mentioned in @var{syntaxes}. It stops when it encountersthe beginning of the buffer, or position @var{limit} (if specified), ora character it is not supposed to skip.If @var{syntaxes} starts with @samp{^}, then the function skipscharacters whose syntax is @emph{not} in @var{syntaxes}.The return value indicates the distance traveled. It is an integer thatis zero or less.@end defun@defun backward-prefix-charsThis function moves point backward over any number of characters withexpression prefix syntax. This includes both characters in theexpression prefix syntax class, and characters with the @samp{p} flag.@end defun@node Parsing Expressions@section Parsing Balanced Expressions Here are several functions for parsing and scanning balancedexpressions, also known as @dfn{sexps}. Basically, a sexp is either abalanced parenthetical grouping, or a symbol name (a sequence ofcharacters whose syntax is either word constituent or symbolconstituent). However, characters whose syntax is expression prefixare treated as part of the sexp if they appear next to it. The syntax table controls the interpretation of characters, so thesefunctions can be used for Lisp expressions when in Lisp mode and for Cexpressions when in C mode. @xref{List Motion}, for convenienthigher-level functions for moving over balanced expressions. A syntax table only describes how each character changes the stateof 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 characters inside the string donot have any particular syntax to identify them as such. For example(note that 15 is the syntax code for generic string delimiters),@example(put-text-property 1 9 'syntax-table '(15 . nil))@end example@noindentdoes not tell Emacs that the first eight chars of the current bufferare a string, but rather that they are all string delimiters. As aresult, Emacs treats them as four consecutive empty string constants. Every time you use the parser, you specify it a starting state aswell as a starting position. If you omit the starting state, thedefault is ``top level in parenthesis structure,'' as it would be atthe beginning of a function definition. (This is the case for@code{forward-sexp}, which blindly assumes that the starting point isin such a state.)@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-commentThis function parses a sexp in the current buffer starting at@var{start}, not scanning past @var{limit}. It stops at position@var{limit} or when certain criteria described below are met, and setspoint to the location where parsing stops. It returns a valuedescribing the status of the parse at the point where it stops.If @var{state} is @code{nil}, @var{start} is assumed to be at the toplevel of parenthesis structure, such as the beginning of a functiondefinition. Alternatively, you might wish to resume parsing in themiddle of the structure. To do this, you must provide a @var{state}argument that describes the initial status of parsing.@cindex parenthesis depthIf the third argument @var{target-depth} is non-@code{nil}, parsingstops if the depth in parentheses becomes equal to @var{target-depth}.The depth starts at 0, or at whatever is given in @var{state}.If the fourth argument @var{stop-before} is non-@code{nil}, parsingstops when it comes to any character that starts a sexp. If@var{stop-comment} is non-@code{nil}, parsing stops when it comes to thestart of a comment. If @var{stop-comment} is the symbol@code{syntax-table}, parsing stops after the start of a comment or astring, or the end of a comment or a string, whichever comes first.@cindex parse stateThe fifth argument @var{state} is a nine-element list of the same formas the value of this function, described below. (It is OK to omit thelast element of the nine.) The return value of one call may be used toinitialize the state of the parse on another call to@code{parse-partial-sexp}.The result is a list of nine elements describing the final state ofthe parse:@enumerate 0@itemThe depth in parentheses, counting from 0.@item@cindex innermost containing parenthesesThe character position of the start of the innermost parentheticalgrouping containing the stopping point; @code{nil} if none.@item@cindex previous complete subexpressionThe character position of the start of the last complete subexpressionterminated; @code{nil} if none.@item@cindex inside stringNon-@code{nil} if inside a string. More precisely, this is thecharacter that will terminate the string, or @code{t} if a genericstring delimiter character should terminate it.@item@cindex inside comment@code{t} if inside a comment (of either style),or the comment nesting level if inside a kind of commentthat can be nested.@item@cindex quote character@code{t} if point is just after a quote character.@itemThe minimum parenthesis depth encountered during this scan.@itemWhat 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 ageneric comment delimiter character.@itemThe string or comment start position. While inside a comment, this isthe position where the comment began; while inside a string, this is theposition where the string began. When outside of strings and comments,this element is @code{nil}.@end enumerateElements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.Actually, the return value is currently a list of ten, rather thannine, elements and @var{state} is allowed to be a list of ten elementsas well. However, the meaning of the tenth element is subject tochange and only the first eight elements of @var{state} need to bespecified.@cindex indenting with parenthesesThis function is most often used to compute indentation for languagesthat have nested parentheses.@end defun@defun scan-lists from count depthThis function scans forward @var{count} balanced parenthetical groupingsfrom 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 thatvalue. The only candidates for stopping are places where the depth inparentheses becomes zero; @code{scan-lists} counts @var{count} suchplaces and then stops. Thus, a positive value for @var{depth} means goout @var{depth} levels of parenthesis.Scanning ignores comments if @code{parse-sexp-ignore-comments} isnon-@code{nil}.If the scan reaches the beginning or end of the buffer (or itsaccessible 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} isreturned.@end defun@defun scan-sexps from countThis function scans forward @var{count} sexps from position @var{from}.It returns the position where the scan stops. If @var{count} isnegative, the scan moves backwards.Scanning ignores comments if @code{parse-sexp-ignore-comments} isnon-@code{nil}.If the scan reaches the beginning or end of (the accessible part of) thebuffer while in the middle of a parenthetical grouping, an error issignaled. If it reaches the beginning or end between groupings butbefore count is used up, @code{nil} is returned.@end defun@defvar multibyte-syntax-as-symbol@tindex multibyte-syntax-as-symbolIf this variable is non-@code{nil}, @code{scan-sexps} treats allnon-@acronym{ASCII} characters as symbol constituents regardlessof what the syntax table says about them. (However, text propertiescan still override the syntax.)@end defvar@defopt parse-sexp-ignore-comments@cindex skipping commentsIf the value is non-@code{nil}, then comments are treated aswhitespace by the functions in this section and by @code{forward-sexp}.@end defopt@vindex parse-sexp-lookup-propertiesThe behaviour of @code{parse-partial-sexp} is also affected by@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).You can use @code{forward-comment} to move forward or backward overone comment or several comments.@defun forward-comment countThis function moves point forward across @var{count} complete comments(that is, including the starting delimiter and the terminatingdelimiter if any), plus any whitespace encountered on the way. Itmoves backward if @var{count} is negative. If it encounters anythingother than a comment or whitespace, it stops, leaving point at theplace where it stopped. This includes (for instance) finding the endof a comment when moving forward and expecting the beginning of one.The function also stops immediately after moving over the specifiednumber of complete comments. If @var{count} comments are found asexpected, with nothing except whitespace between them, it returns@code{t}; otherwise it returns @code{nil}.This function cannot tell whether the ``comments'' it traverses areembedded within a string. If they look like comments, it treats themas comments.@end defunTo move forward over all comments and whitespace following point, use@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a goodargument to use, because the number of comments in the buffer cannotexceed that many.@node Standard Syntax Tables@section Some Standard Syntax Tables Most of the major modes in Emacs have their own syntax tables. Hereare several of them:@defun standard-syntax-tableThis function returns the standard syntax table, which is the syntaxtable used in Fundamental mode.@end defun@defvar text-mode-syntax-tableThe value of this variable is the syntax table used in Text mode.@end defvar@defvar c-mode-syntax-tableThe value of this variable is the syntax table for C-mode buffers.@end defvar@defvar emacs-lisp-mode-syntax-tableThe value of this variable is the syntax table used in Emacs Lisp modeby editing commands. (It has no effect on the Lisp @code{read}function.)@end defvar@node Syntax Table Internals@section Syntax Table Internals@cindex syntax table internals Lisp programs don't usually work with the elements directly; theLisp-level syntax table functions usually work with syntax descriptors(@pxref{Syntax Descriptors}). Nonetheless, here we document theinternal format. This format is used mostly when manipulatingsyntax properties. Each element of a syntax table is a cons cell of the form@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car},@var{syntax-code}, is an integer that encodes the syntax class, and anyflags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} ifa character to match was specified. This table gives the value of @var{syntax-code} which correspondsto each syntactic type.@multitable @columnfractions .05 .3 .3 .3@item@tab@i{Integer} @i{Class}@tab@i{Integer} @i{Class}@tab@i{Integer} @i{Class}@item@tab0 @ @ whitespace@tab5 @ @ close parenthesis@tab10 @ @ character quote@item@tab1 @ @ punctuation@tab6 @ @ expression prefix@tab11 @ @ comment-start@item@tab2 @ @ word@tab7 @ @ string quote@tab12 @ @ comment-end@item@tab3 @ @ symbol@tab8 @ @ paired delimiter@tab13 @ @ inherit@item@tab4 @ @ open parenthesis@tab9 @ @ escape@tab14 @ @ generic comment@item@tab15 @ generic string@end 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 theleast significant bit. This table gives the power of two whichcorresponds to each syntax flag.@multitable @columnfractions .05 .3 .3 .3@item@tab@i{Prefix} @i{Flag}@tab@i{Prefix} @i{Flag}@tab@i{Prefix} @i{Flag}@item@tab@samp{1} @ @ @code{(lsh 1 16)}@tab@samp{4} @ @ @code{(lsh 1 19)}@tab@samp{b} @ @ @code{(lsh 1 21)}@item@tab@samp{2} @ @ @code{(lsh 1 17)}@tab@samp{p} @ @ @code{(lsh 1 20)}@tab@samp{n} @ @ @code{(lsh 1 22)}@item@tab@samp{3} @ @ @code{(lsh 1 18)}@end multitable@defun string-to-syntax @var{desc}This function returns the internal form @code{(@var{syntax-code} .@var{matching-char})} corresponding to the syntax descriptor @var{desc}.@end defun@node Categories@section Categories@cindex categories of characters @dfn{Categories} provide an alternate way of classifying characterssyntactically. You can define several categories as needed, thenindependently assign each character to one or more categories. Unlikesyntax classes, categories are not mutually exclusive; it is normal forone character to belong to several categories. Each buffer has a @dfn{category table} which records which categoriesare defined and also which characters belong to each category. Eachcategory table defines its own categories, but normally these areinitialized by copying from the standard categories table, so that thestandard categories are available in all modes. Each category has a name, which is an @acronym{ASCII} printing character inthe range @w{@samp{ }} to @samp{~}. You specify the name of a categorywhen 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{categoryset}---a bool-vector---that indicates which categories character @var{c}belongs to. In this category set, if the element at index @var{cat} is@code{t}, that means category @var{cat} is a member of the set, and thatcharacter @var{c} belongs to category @var{cat}.For the next three functions, the optional argument @var{table}defaults to the current buffer's category table.@defun define-category char docstring &optional tableThis function defines a new category, with name @var{char} anddocumentation @var{docstring}, for the category table @var{table},@end defun@defun category-docstring category &optional tableThis function returns the documentation string of category @var{category}in category table @var{table}.@example(category-docstring ?a) @result{} "ASCII"(category-docstring ?l) @result{} "Latin"@end example@end defun@defun get-unused-category &optional tableThis function returns a category name (a character) which is notcurrently defined in @var{table}. If all possible categories are in usein @var{table}, it returns @code{nil}.@end defun@defun category-tableThis function returns the current buffer's category table.@end defun@defun category-table-p objectThis function returns @code{t} if @var{object} is a category table,otherwise @code{nil}.@end defun@defun standard-category-tableThis function returns the standard category table.@end defun@defun copy-category-table &optional tableThis function constructs a copy of @var{table} and returns it. If@var{table} is not supplied (or is @code{nil}), it returns a copy of thestandard category table. Otherwise, an error is signaled if @var{table}is not a category table.@end defun@defun set-category-table tableThis function makes @var{table} the category table for the currentbuffer. It returns @var{table}.@end defun@defun make-category-table@tindex make-category-tableThis creates and returns an empty category table. In an empty categorytable, no categories have been allocated, and no characters belong toany categories.@end defun@defun make-category-set categoriesThis function returns a new category set---a bool-vector---whose initialcontents are the categories listed in the string @var{categories}. Theelements of @var{categories} should be category names; the new categoryset has @code{t} for each of those categories, and @code{nil} for allother categories.@example(make-category-set "al") @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"@end example@end defun@defun char-category-set charThis function returns the category set for character @var{char} in thecurrent buffer's category table. This is the bool-vector whichrecords which categories the character @var{char} belongs to. Thefunction @code{char-category-set} does not allocate storage, becauseit returns the same bool-vector that exists in the category table.@example(char-category-set ?a) @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"@end example@end defun@defun category-set-mnemonics category-setThis function converts the category set @var{category-set} into a stringcontaining the characters that designate the categories that are membersof the set.@example(category-set-mnemonics (char-category-set ?a)) @result{} "al"@end example@end defun@defun modify-category-entry character category &optional table resetThis function modifies the category set of @var{character} in categorytable @var{table} (which defaults to the current buffer's categorytable).Normally, it modifies the category set by adding @var{category} to it.But if @var{reset} is non-@code{nil}, then it deletes @var{category}instead.@end defun@deffn Command describe-categories &optional buffer-or-nameThis function describes the category specifications in the currentcategory table. It inserts the descriptions in a buffer, and thendisplays that buffer. If @var{buffer-or-name} is non-@code{nil}, itdescribes the category table of that buffer instead.@end deffn@ignore arch-tag: 4d914e96-0283-445c-9233-75d33662908c@end ignore