*** empty log message ***
[emacs.git] / lispref / syntax.texi
blobeb0591b855cec72160e8e82b672243904bc05327
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/syntax
7 @node Syntax Tables, Abbrevs, Searching and Matching, Top
8 @chapter Syntax Tables
9 @cindex parsing
10 @cindex syntax table
11 @cindex text parsing
13   A @dfn{syntax table} specifies the syntactic textual function of each
14 character.  This information is used by the @dfn{parsing functions}, the
15 complex movement commands, and others to determine where words, symbols,
16 and other syntactic constructs begin and end.  The current syntax table
17 controls the meaning of the word motion functions (@pxref{Word Motion})
18 and the list motion functions (@pxref{List Motion}), as well as the
19 functions in this chapter.
21 @menu
22 * Basics: Syntax Basics.     Basic concepts of syntax tables.
23 * Desc: Syntax Descriptors.  How characters are classified.
24 * Syntax Table Functions::   How to create, examine and alter syntax tables.
25 * Syntax Properties::        Overriding syntax with text properties.
26 * Motion and Syntax::        Moving over characters with certain syntaxes.
27 * Parsing Expressions::      Parsing balanced expressions
28                                 using the syntax table.
29 * Standard Syntax Tables::   Syntax tables used by various major modes.
30 * Syntax Table Internals::   How syntax table information is stored.
31 * Categories::               Another way of classifying character syntax.
32 @end menu
34 @node Syntax Basics
35 @section Syntax Table Concepts
37 @ifnottex
38   A @dfn{syntax table} provides Emacs with the information that
39 determines the syntactic use of each character in a buffer.  This
40 information is used by the parsing commands, the complex movement
41 commands, and others to determine where words, symbols, and other
42 syntactic constructs begin and end.  The current syntax table controls
43 the meaning of the word motion functions (@pxref{Word Motion}) and the
44 list motion functions (@pxref{List Motion}) as well as the functions in
45 this chapter.
46 @end ifnottex
48   A syntax table is a char-table (@pxref{Char-Tables}).  The element at
49 index @var{c} describes the character with code @var{c}.  The element's
50 value should be a list that encodes the syntax of the character in
51 question.
53   Syntax tables are used only for moving across text, not for the Emacs
54 Lisp reader.  Emacs Lisp uses built-in syntactic rules when reading Lisp
55 expressions, and these rules cannot be changed.  (Some Lisp systems
56 provide ways to redefine the read syntax, but we decided to leave this
57 feature out of Emacs Lisp for simplicity.)
59   Each buffer has its own major mode, and each major mode has its own
60 idea of the syntactic class of various characters.  For example, in Lisp
61 mode, the character @samp{;} begins a comment, but in C mode, it
62 terminates a statement.  To support these variations, Emacs makes the
63 choice of syntax table local to each buffer.  Typically, each major
64 mode has its own syntax table and installs that table in each buffer
65 that uses that mode.  Changing this table alters the syntax in all
66 those buffers as well as in any buffers subsequently put in that mode.
67 Occasionally several similar modes share one syntax table.
68 @xref{Example Major Modes}, for an example of how to set up a syntax
69 table.
71 A syntax table can inherit the data for some characters from the
72 standard syntax table, while specifying other characters itself.  The
73 ``inherit'' syntax class means ``inherit this character's syntax from
74 the standard syntax table.''  Just changing the standard syntax for a
75 character affects all syntax tables that inherit from it.
77 @defun syntax-table-p object
78 This function returns @code{t} if @var{object} is a syntax table.
79 @end defun
81 @node Syntax Descriptors
82 @section Syntax Descriptors
83 @cindex syntax classes
85   This section describes the syntax classes and flags that denote the
86 syntax of a character, and how they are represented as a @dfn{syntax
87 descriptor}, which is a Lisp string that you pass to
88 @code{modify-syntax-entry} to specify the syntax you want.
90   The syntax table specifies a syntax class for each character.  There
91 is no necessary relationship between the class of a character in one
92 syntax table and its class in any other table.
94   Each class is designated by a mnemonic character, which serves as the
95 name of the class when you need to specify a class.  Usually the
96 designator character is one that is often assigned that class; however,
97 its meaning as a designator is unvarying and independent of what syntax
98 that character currently has.  Thus, @samp{\} as a designator character
99 always gives ``escape character'' syntax, regardless of what syntax
100 @samp{\} currently has.
102 @cindex syntax descriptor
103   A syntax descriptor is a Lisp string that specifies a syntax class, a
104 matching character (used only for the parenthesis classes) and flags.
105 The first character is the designator for a syntax class.  The second
106 character is the character to match; if it is unused, put a space there.
107 Then come the characters for any desired flags.  If no matching
108 character or flags are needed, one character is sufficient.
110   For example, the syntax descriptor for the character @samp{*} in C
111 mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
112 unused, second character of a comment-starter, first character of a
113 comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
114 punctuation, matching character slot unused, first character of a
115 comment-starter, second character of a comment-ender).
117 @menu
118 * Syntax Class Table::      Table of syntax classes.
119 * Syntax Flags::            Additional flags each character can have.
120 @end menu
122 @node Syntax Class Table
123 @subsection Table of Syntax Classes
125   Here is a table of syntax classes, the characters that stand for them,
126 their meanings, and examples of their use.
128 @deffn {Syntax class} @w{whitespace character}
129 @dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
130 separate symbols and words from each other.  Typically, whitespace
131 characters have no other syntactic significance, and multiple whitespace
132 characters are syntactically equivalent to a single one.  Space, tab,
133 newline and formfeed are classified as whitespace in almost all major
134 modes.
135 @end deffn
137 @deffn {Syntax class} @w{word constituent}
138 @dfn{Word constituents} (designated by @samp{w}) are parts of normal
139 English words and are typically used in variable and command names in
140 programs.  All upper- and lower-case letters, and the digits, are typically
141 word constituents.
142 @end deffn
144 @deffn {Syntax class} @w{symbol constituent}
145 @dfn{Symbol constituents} (designated by @samp{_}) are the extra
146 characters that are used in variable and command names along with word
147 constituents.  For example, the symbol constituents class is used in
148 Lisp mode to indicate that certain characters may be part of symbol
149 names even though they are not part of English words.  These characters
150 are @samp{$&*+-_<>}.  In standard C, the only non-word-constituent
151 character that is valid in symbols is underscore (@samp{_}).
152 @end deffn
154 @deffn {Syntax class} @w{punctuation character}
155 @dfn{Punctuation characters} (designated by @samp{.}) are those
156 characters that are used as punctuation in English, or are used in some
157 way in a programming language to separate symbols from one another.
158 Most programming language modes, including Emacs Lisp mode, have no
159 characters in this class since the few characters that are not symbol or
160 word constituents all have other uses.
161 @end deffn
163 @deffn {Syntax class} @w{open parenthesis character}
164 @deffnx {Syntax class} @w{close parenthesis character}
165 @cindex parenthesis syntax
166 Open and close @dfn{parenthesis characters} are characters used in
167 dissimilar pairs to surround sentences or expressions.  Such a grouping
168 is begun with an open parenthesis character and terminated with a close.
169 Each open parenthesis character matches a particular close parenthesis
170 character, and vice versa.  Normally, Emacs indicates momentarily the
171 matching open parenthesis when you insert a close parenthesis.
172 @xref{Blinking}.
174 The class of open parentheses is designated by @samp{(}, and that of
175 close parentheses by @samp{)}.
177 In English text, and in C code, the parenthesis pairs are @samp{()},
178 @samp{[]}, and @samp{@{@}}.  In Emacs Lisp, the delimiters for lists and
179 vectors (@samp{()} and @samp{[]}) are classified as parenthesis
180 characters.
181 @end deffn
183 @deffn {Syntax class} @w{string quote}
184 @dfn{String quote characters} (designated by @samp{"}) are used in
185 many languages, including Lisp and C, to delimit string constants.  The
186 same string quote character appears at the beginning and the end of a
187 string.  Such quoted strings do not nest.
189 The parsing facilities of Emacs consider a string as a single token.
190 The usual syntactic meanings of the characters in the string are
191 suppressed.
193 The Lisp modes have two string quote characters: double-quote (@samp{"})
194 and vertical bar (@samp{|}).  @samp{|} is not used in Emacs Lisp, but it
195 is used in Common Lisp.  C also has two string quote characters:
196 double-quote for strings, and single-quote (@samp{'}) for character
197 constants.
199 English text has no string quote characters because English is not a
200 programming language.  Although quotation marks are used in English,
201 we do not want them to turn off the usual syntactic properties of
202 other characters in the quotation.
203 @end deffn
205 @deffn {Syntax class} @w{escape}
206 An @dfn{escape character} (designated by @samp{\}) starts an escape
207 sequence such as is used in C string and character constants.  The
208 character @samp{\} belongs to this class in both C and Lisp.  (In C, it
209 is used thus only inside strings, but it turns out to cause no trouble
210 to treat it this way throughout C code.)
212 Characters in this class count as part of words if
213 @code{words-include-escapes} is non-@code{nil}.  @xref{Word Motion}.
214 @end deffn
216 @deffn {Syntax class} @w{character quote}
217 A @dfn{character quote character} (designated by @samp{/}) quotes the
218 following character so that it loses its normal syntactic meaning.  This
219 differs from an escape character in that only the character immediately
220 following is ever affected.
222 Characters in this class count as part of words if
223 @code{words-include-escapes} is non-@code{nil}.  @xref{Word Motion}.
225 This class is used for backslash in @TeX{} mode.
226 @end deffn
228 @deffn {Syntax class} @w{paired delimiter}
229 @dfn{Paired delimiter characters} (designated by @samp{$}) are like
230 string quote characters except that the syntactic properties of the
231 characters between the delimiters are not suppressed.  Only @TeX{} mode
232 uses a paired delimiter presently---the @samp{$} that both enters and
233 leaves math mode.
234 @end deffn
236 @deffn {Syntax class} @w{expression prefix}
237 An @dfn{expression prefix operator} (designated by @samp{'}) is used for
238 syntactic operators that are considered as part of an expression if they
239 appear next to one.  In Lisp modes, these characters include the
240 apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
241 macros), and @samp{#} (used in the read syntax for certain data types).
242 @end deffn
244 @deffn {Syntax class} @w{comment starter}
245 @deffnx {Syntax class} @w{comment ender}
246 @cindex comment syntax
247 The @dfn{comment starter} and @dfn{comment ender} characters are used in
248 various languages to delimit comments.  These classes are designated
249 by @samp{<} and @samp{>}, respectively.
251 English text has no comment characters.  In Lisp, the semicolon
252 (@samp{;}) starts a comment and a newline or formfeed ends one.
253 @end deffn
255 @deffn {Syntax class} @w{inherit}
256 This syntax class does not specify a particular syntax.  It says to look
257 in the standard syntax table to find the syntax of this character.  The
258 designator for this syntax code is @samp{@@}.
259 @end deffn
261 @deffn {Syntax class} @w{generic comment delimiter}
262 A @dfn{generic comment delimiter} character starts or ends a special
263 kind of comment.  @emph{Any} generic comment delimiter matches
264 @emph{any} generic comment delimiter, but they cannot match a comment
265 starter or comment ender; generic comment delimiters can only match each
266 other.
268 This syntax class is primarily meant for use with the
269 @code{syntax-table} text property (@pxref{Syntax Properties}).  You can
270 mark any range of characters as forming a comment, by giving the first
271 and last characters of the range @code{syntax-table} properties
272 identifying them as generic comment delimiters.
273 @end deffn
275 @deffn {Syntax class} @w{generic string delimiter}
276 A @dfn{generic string delimiter} character starts or ends a string.
277 This class differs from the string quote class in that @emph{any}
278 generic string delimiter can match any other generic string delimiter;
279 but they do not match ordinary string quote characters.
281 This syntax class is primarily meant for use with the
282 @code{syntax-table} text property (@pxref{Syntax Properties}).  You can
283 mark any range of characters as forming a string constant, by giving the
284 first and last characters of the range @code{syntax-table} properties
285 identifying them as generic string delimiters.
286 @end deffn
288 @node Syntax Flags
289 @subsection Syntax Flags
290 @cindex syntax flags
292   In addition to the classes, entries for characters in a syntax table
293 can specify flags.  There are seven possible flags, represented by the
294 characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n},
295 and @samp{p}.
297   All the flags except @samp{n} and @samp{p} are used to describe
298 multi-character comment delimiters.  The digit flags indicate that a
299 character can @emph{also} be part of a comment sequence, in addition to
300 the syntactic properties associated with its character class.  The flags
301 are independent of the class and each other for the sake of characters
302 such as @samp{*} in C mode, which is a punctuation character, @emph{and}
303 the second character of a start-of-comment sequence (@samp{/*}),
304 @emph{and} the first character of an end-of-comment sequence
305 (@samp{*/}).
307   Here is a table of the possible flags for a character @var{c},
308 and what they mean:
310 @itemize @bullet
311 @item
312 @samp{1} means @var{c} is the start of a two-character comment-start
313 sequence.
315 @item
316 @samp{2} means @var{c} is the second character of such a sequence.
318 @item
319 @samp{3} means @var{c} is the start of a two-character comment-end
320 sequence.
322 @item
323 @samp{4} means @var{c} is the second character of such a sequence.
325 @item
326 @c Emacs 19 feature
327 @samp{b} means that @var{c} as a comment delimiter belongs to the
328 alternative ``b'' comment style.
330 Emacs supports two comment styles simultaneously in any one syntax
331 table.  This is for the sake of C++.  Each style of comment syntax has
332 its own comment-start sequence and its own comment-end sequence.  Each
333 comment must stick to one style or the other; thus, if it starts with
334 the comment-start sequence of style ``b'', it must also end with the
335 comment-end sequence of style ``b''.
337 The two comment-start sequences must begin with the same character; only
338 the second character may differ.  Mark the second character of the
339 ``b''-style comment-start sequence with the @samp{b} flag.
341 A comment-end sequence (one or two characters) applies to the ``b''
342 style if its first character has the @samp{b} flag set; otherwise, it
343 applies to the ``a'' style.
345 The appropriate comment syntax settings for C++ are as follows:
347 @table @asis
348 @item @samp{/}
349 @samp{124b}
350 @item @samp{*}
351 @samp{23}
352 @item newline
353 @samp{>b}
354 @end table
356 This defines four comment-delimiting sequences:
358 @table @asis
359 @item @samp{/*}
360 This is a comment-start sequence for ``a'' style because the
361 second character, @samp{*}, does not have the @samp{b} flag.
363 @item @samp{//}
364 This is a comment-start sequence for ``b'' style because the second
365 character, @samp{/}, does have the @samp{b} flag.
367 @item @samp{*/}
368 This is a comment-end sequence for ``a'' style because the first
369 character, @samp{*}, does not have the @samp{b} flag.
371 @item newline
372 This is a comment-end sequence for ``b'' style, because the newline
373 character has the @samp{b} flag.
374 @end table
376 @item
377 @samp{n} on a comment delimiter character specifies
378 that this kind of comment can be nested.  For a two-character
379 comment delimiter, @samp{n} on either character makes it
380 nestable.
382 @item
383 @c Emacs 19 feature
384 @samp{p} identifies an additional ``prefix character'' for Lisp syntax.
385 These characters are treated as whitespace when they appear between
386 expressions.  When they appear within an expression, they are handled
387 according to their usual syntax codes.
389 The function @code{backward-prefix-chars} moves back over these
390 characters, as well as over characters whose primary syntax class is
391 prefix (@samp{'}).  @xref{Motion and Syntax}.
392 @end itemize
394 @node Syntax Table Functions
395 @section Syntax Table Functions
397   In this section we describe functions for creating, accessing and
398 altering syntax tables.
400 @defun make-syntax-table
401 This function creates a new syntax table.  It inherits the syntax for
402 letters and control characters from the standard syntax table.  For
403 other characters, the syntax is copied from the standard syntax table.
405 Most major mode syntax tables are created in this way.
406 @end defun
408 @defun copy-syntax-table &optional table
409 This function constructs a copy of @var{table} and returns it.  If
410 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
411 current syntax table.  Otherwise, an error is signaled if @var{table} is
412 not a syntax table.
413 @end defun
415 @deffn Command modify-syntax-entry char syntax-descriptor  &optional table
416 This function sets the syntax entry for @var{char} according to
417 @var{syntax-descriptor}.  The syntax is changed only for @var{table},
418 which defaults to the current buffer's syntax table, and not in any
419 other syntax table.  The argument @var{syntax-descriptor} specifies the
420 desired syntax; this is a string beginning with a class designator
421 character, and optionally containing a matching character and flags as
422 well.  @xref{Syntax Descriptors}.
424 This function always returns @code{nil}.  The old syntax information in
425 the table for this character is discarded.
427 An error is signaled if the first character of the syntax descriptor is not
428 one of the twelve syntax class designator characters.  An error is also
429 signaled if @var{char} is not a character.
431 @example
432 @group
433 @exdent @r{Examples:}
435 ;; @r{Put the space character in class whitespace.}
436 (modify-syntax-entry ?\  " ")
437      @result{} nil
438 @end group
440 @group
441 ;; @r{Make @samp{$} an open parenthesis character,}
442 ;;   @r{with @samp{^} as its matching close.}
443 (modify-syntax-entry ?$ "(^")
444      @result{} nil
445 @end group
447 @group
448 ;; @r{Make @samp{^} a close parenthesis character,}
449 ;;   @r{with @samp{$} as its matching open.}
450 (modify-syntax-entry ?^ ")$")
451      @result{} nil
452 @end group
454 @group
455 ;; @r{Make @samp{/} a punctuation character,}
456 ;;   @r{the first character of a start-comment sequence,}
457 ;;   @r{and the second character of an end-comment sequence.}
458 ;;   @r{This is used in C mode.}
459 (modify-syntax-entry ?/ ". 14")
460      @result{} nil
461 @end group
462 @end example
463 @end deffn
465 @defun char-syntax character
466 This function returns the syntax class of @var{character}, represented
467 by its mnemonic designator character.  This returns @emph{only} the
468 class, not any matching parenthesis or flags.
470 An error is signaled if @var{char} is not a character.
472 The following examples apply to C mode.  The first example shows that
473 the syntax class of space is whitespace (represented by a space).  The
474 second example shows that the syntax of @samp{/} is punctuation.  This
475 does not show the fact that it is also part of comment-start and -end
476 sequences.  The third example shows that open parenthesis is in the class
477 of open parentheses.  This does not show the fact that it has a matching
478 character, @samp{)}.
480 @example
481 @group
482 (string (char-syntax ?\ ))
483      @result{} " "
484 @end group
486 @group
487 (string (char-syntax ?/))
488      @result{} "."
489 @end group
491 @group
492 (string (char-syntax ?\())
493      @result{} "("
494 @end group
495 @end example
497 We use @code{string} to make it easier to see the character returned by
498 @code{char-syntax}.
499 @end defun
501 @defun set-syntax-table table
502 This function makes @var{table} the syntax table for the current buffer.
503 It returns @var{table}.
504 @end defun
506 @defun syntax-table
507 This function returns the current syntax table, which is the table for
508 the current buffer.
509 @end defun
511 @defmac with-syntax-table @var{table} @var{body}...
512 @tindex with-syntax-table
513 This macro executes @var{body} using @var{table} as the current syntax
514 table.  It returns the value of the last form in @var{body}, after
515 restoring the old current syntax table.
517 Since each buffer has its own current syntax table, we should make that
518 more precise: @code{with-syntax-table} temporarily alters the current
519 syntax table of whichever buffer is current at the time the macro
520 execution starts.  Other buffers are not affected.
521 @end defmac
523 @node Syntax Properties
524 @section Syntax Properties
525 @kindex syntax-table @r{(text property)}
527 When the syntax table is not flexible enough to specify the syntax of a
528 language, you can use @code{syntax-table} text properties to override
529 the syntax table for specific character occurrences in the buffer.
530 @xref{Text Properties}.
532 The valid values of @code{syntax-table} text property are:
534 @table @asis
535 @item @var{syntax-table}
536 If the property value is a syntax table, that table is used instead of
537 the current buffer's syntax table to determine the syntax for this
538 occurrence of the character.
540 @item @code{(@var{syntax-code} . @var{matching-char})}
541 A cons cell of this format specifies the syntax for this
542 occurrence of the character.
544 @item @code{nil}
545 If the property is @code{nil}, the character's syntax is determined from
546 the current syntax table in the usual way.
547 @end table
549 @defvar parse-sexp-lookup-properties
550 If this is non-@code{nil}, the syntax scanning functions pay attention
551 to syntax text properties.  Otherwise they use only the current syntax
552 table.
553 @end defvar
555 @node Motion and Syntax
556 @section Motion and Syntax
558   This section describes functions for moving across characters that
559 have certain syntax classes.
561 @defun skip-syntax-forward syntaxes &optional limit
562 This function moves point forward across characters having syntax classes
563 mentioned in @var{syntaxes}.  It stops when it encounters the end of
564 the buffer, or position @var{limit} (if specified), or a character it is
565 not supposed to skip.
567 If @var{syntaxes} starts with @samp{^}, then the function skips
568 characters whose syntax is @emph{not} in @var{syntaxes}.
570 The return value is the distance traveled, which is a nonnegative
571 integer.
572 @end defun
574 @defun skip-syntax-backward syntaxes &optional limit
575 This function moves point backward across characters whose syntax
576 classes are mentioned in @var{syntaxes}.  It stops when it encounters
577 the beginning of the buffer, or position @var{limit} (if specified), or
578 a character it is not supposed to skip.
580 If @var{syntaxes} starts with @samp{^}, then the function skips
581 characters whose syntax is @emph{not} in @var{syntaxes}.
583 The return value indicates the distance traveled.  It is an integer that
584 is zero or less.
585 @end defun
587 @defun backward-prefix-chars
588 This function moves point backward over any number of characters with
589 expression prefix syntax.  This includes both characters in the
590 expression prefix syntax class, and characters with the @samp{p} flag.
591 @end defun
593 @node Parsing Expressions
594 @section Parsing Balanced Expressions
596   Here are several functions for parsing and scanning balanced
597 expressions, also known as @dfn{sexps}, in which parentheses match in
598 pairs.  The syntax table controls the interpretation of characters, so
599 these functions can be used for Lisp expressions when in Lisp mode and
600 for C expressions when in C mode.  @xref{List Motion}, for convenient
601 higher-level functions for moving over balanced expressions.
603 @defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
604 This function parses a sexp in the current buffer starting at
605 @var{start}, not scanning past @var{limit}.  It stops at position
606 @var{limit} or when certain criteria described below are met, and sets
607 point to the location where parsing stops.  It returns a value
608 describing the status of the parse at the point where it stops.
610 If @var{state} is @code{nil}, @var{start} is assumed to be at the top
611 level of parenthesis structure, such as the beginning of a function
612 definition.  Alternatively, you might wish to resume parsing in the
613 middle of the structure.  To do this, you must provide a @var{state}
614 argument that describes the initial status of parsing.
616 @cindex parenthesis depth
617 If the third argument @var{target-depth} is non-@code{nil}, parsing
618 stops if the depth in parentheses becomes equal to @var{target-depth}.
619 The depth starts at 0, or at whatever is given in @var{state}.
621 If the fourth argument @var{stop-before} is non-@code{nil}, parsing
622 stops when it comes to any character that starts a sexp.  If
623 @var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
624 start of a comment.  If @var{stop-comment} is the symbol
625 @code{syntax-table}, parsing stops after the start of a comment or a
626 string, or the end of a comment or a string, whichever comes first.
628 @cindex parse state
629 The fifth argument @var{state} is a nine-element list of the same form
630 as the value of this function, described below.  (It is OK to omit the
631 last element of the nine.)  The return value of one call may be used to
632 initialize the state of the parse on another call to
633 @code{parse-partial-sexp}.
635 The result is a list of nine elements describing the final state of
636 the parse:
638 @enumerate 0
639 @item 
640 The depth in parentheses, counting from 0.
642 @item 
643 @cindex innermost containing parentheses
644 The character position of the start of the innermost parenthetical
645 grouping containing the stopping point; @code{nil} if none.
647 @item 
648 @cindex previous complete subexpression
649 The character position of the start of the last complete subexpression
650 terminated; @code{nil} if none.
652 @item 
653 @cindex inside string
654 Non-@code{nil} if inside a string.  More precisely, this is the
655 character that will terminate the string, or @code{t} if a generic
656 string delimiter character should terminate it.
658 @item 
659 @cindex inside comment
660 @code{t} if inside a comment (of either style),
661 or the comment nesting level if inside a kind of comment
662 that can be nested.
664 @item 
665 @cindex quote character
666 @code{t} if point is just after a quote character.
668 @item 
669 The minimum parenthesis depth encountered during this scan.
671 @item
672 What kind of comment is active: @code{nil} for a comment of style ``a'',
673 @code{t} for a comment of style ``b'', and @code{syntax-table} for
674 a comment that should be ended by a generic comment delimiter character.
676 @item
677 The string or comment start position.  While inside a comment, this is
678 the position where the comment began; while inside a string, this is the
679 position where the string began.  When outside of strings and comments,
680 this element is @code{nil}.
681 @end enumerate
683 Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
685 @cindex indenting with parentheses
686 This function is most often used to compute indentation for languages
687 that have nested parentheses.
688 @end defun
690 @defun scan-lists from count depth
691 This function scans forward @var{count} balanced parenthetical groupings
692 from position @var{from}.  It returns the position where the scan stops.
693 If @var{count} is negative, the scan moves backwards.
695 If @var{depth} is nonzero, parenthesis depth counting begins from that
696 value.  The only candidates for stopping are places where the depth in
697 parentheses becomes zero; @code{scan-lists} counts @var{count} such
698 places and then stops.  Thus, a positive value for @var{depth} means go
699 out @var{depth} levels of parenthesis.
701 Scanning ignores comments if @code{parse-sexp-ignore-comments} is
702 non-@code{nil}.
704 If the scan reaches the beginning or end of the buffer (or its
705 accessible portion), and the depth is not zero, an error is signaled.
706 If the depth is zero but the count is not used up, @code{nil} is
707 returned.
708 @end defun
710 @defun scan-sexps from count
711 This function scans forward @var{count} sexps from position @var{from}.
712 It returns the position where the scan stops.  If @var{count} is
713 negative, the scan moves backwards.
715 Scanning ignores comments if @code{parse-sexp-ignore-comments} is
716 non-@code{nil}.
718 If the scan reaches the beginning or end of (the accessible part of) the
719 buffer while in the middle of a parenthetical grouping, an error is
720 signaled.  If it reaches the beginning or end between groupings but
721 before count is used up, @code{nil} is returned.
722 @end defun
724 @defvar multibyte-syntax-as-symbol
725 @tindex multibyte-syntax-as-symbol
726 If this variable is non-@code{nil}, @code{scan-sexps} treats all
727 non-@sc{ascii} characters as symbol constituents regardless
728 of what the syntax table says about them.  (However, text properties
729 can still override the syntax.)
730 @end defvar
732 @defvar parse-sexp-ignore-comments
733 @cindex skipping comments
734 If the value is non-@code{nil}, then comments are treated as
735 whitespace by the functions in this section and by @code{forward-sexp}.
737 In older Emacs versions, this feature worked only when the comment
738 terminator is something like @samp{*/}, and appears only to end a
739 comment.  In languages where newlines terminate comments, it was
740 necessary make this variable @code{nil}, since not every newline is the
741 end of a comment.  This limitation no longer exists.
742 @end defvar
744 You can use @code{forward-comment} to move forward or backward over
745 one comment or several comments.
747 @defun forward-comment count
748 This function moves point forward across @var{count} comments (backward,
749 if @var{count} is negative).  If it finds anything other than a comment
750 or whitespace, it stops, leaving point at the place where it stopped.
751 It also stops after satisfying @var{count}.
752 @end defun
754 To move forward over all comments and whitespace following point, use
755 @code{(forward-comment (buffer-size))}.  @code{(buffer-size)} is a good
756 argument to use, because the number of comments in the buffer cannot
757 exceed that many.
759 @node Standard Syntax Tables
760 @section Some Standard Syntax Tables
762   Most of the major modes in Emacs have their own syntax tables.  Here
763 are several of them:
765 @defun standard-syntax-table
766 This function returns the standard syntax table, which is the syntax
767 table used in Fundamental mode.
768 @end defun
770 @defvar text-mode-syntax-table
771 The value of this variable is the syntax table used in Text mode.
772 @end defvar
774 @defvar c-mode-syntax-table
775 The value of this variable is the syntax table for C-mode buffers.
776 @end defvar
778 @defvar emacs-lisp-mode-syntax-table
779 The value of this variable is the syntax table used in Emacs Lisp mode
780 by editing commands.  (It has no effect on the Lisp @code{read}
781 function.)
782 @end defvar
784 @node Syntax Table Internals
785 @section Syntax Table Internals
786 @cindex syntax table internals
788   Lisp programs don't usually work with the elements directly; the
789 Lisp-level syntax table functions usually work with syntax descriptors
790 (@pxref{Syntax Descriptors}).  Nonetheless, here we document the
791 internal format.
793   Each element of a syntax table is a cons cell of the form
794 @code{(@var{syntax-code} . @var{matching-char})}.  The @sc{car},
795 @var{syntax-code}, is an integer that encodes the syntax class, and any
796 flags.  The @sc{cdr}, @var{matching-char}, is non-@code{nil} if
797 a character to match was specified.
799   This table gives the value of @var{syntax-code} which corresponds
800 to each syntactic type.
802 @multitable @columnfractions .05 .3 .3 .3
803 @item
804 @tab
805 @i{Integer} @i{Class}
806 @tab
807 @i{Integer} @i{Class}
808 @tab
809 @i{Integer} @i{Class}
810 @item
811 @tab
812 0 @ @  whitespace
813 @tab
814 5 @ @  close parenthesis
815 @tab
816 10 @ @  character quote
817 @item
818 @tab
819 1 @ @  punctuation
820 @tab
821 6 @ @  expression prefix
822 @tab
823 11 @ @  comment-start
824 @item
825 @tab
826 2 @ @  word
827 @tab
828 7 @ @  string quote
829 @tab
830 12 @ @  comment-end
831 @item
832 @tab
833 3 @ @  symbol
834 @tab
835 8 @ @  paired delimiter
836 @tab
837 13 @ @  inherit
838 @item
839 @tab
840 4 @ @  open parenthesis
841 @tab
842 9 @ @  escape
843 @tab
844 14 @ @  comment-fence
845 @item
846 @tab
847 15 @  string-fence
848 @end multitable
850   For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
851 (41 is the character code for @samp{)}.)
853   The flags are encoded in higher order bits, starting 16 bits from the
854 least significant bit.  This table gives the power of two which
855 corresponds to each syntax flag.
857 @multitable @columnfractions .05 .3 .3 .3
858 @item
859 @tab
860 @i{Prefix} @i{Flag}
861 @tab
862 @i{Prefix} @i{Flag}
863 @tab
864 @i{Prefix} @i{Flag}
865 @item
866 @tab
867 @samp{1} @ @  @code{(lsh 1 16)}
868 @tab
869 @samp{4} @ @  @code{(lsh 1 19)}
870 @tab
871 @samp{b} @ @  @code{(lsh 1 21)}
872 @item
873 @tab
874 @samp{2} @ @  @code{(lsh 1 17)}
875 @tab
876 @samp{p} @ @  @code{(lsh 1 20)}
877 @tab
878 @samp{n} @ @  @code{(lsh 1 22)}
879 @item
880 @tab
881 @samp{3} @ @  @code{(lsh 1 18)}
882 @end multitable
884 @node Categories
885 @section Categories
886 @cindex categories of characters
888   @dfn{Categories} provide an alternate way of classifying characters
889 syntactically.  You can define several categories as needed, then
890 independently assign each character to one or more categories.  Unlike
891 syntax classes, categories are not mutually exclusive; it is normal for
892 one character to belong to several categories.
894   Each buffer has a @dfn{category table} which records which categories
895 are defined and also which characters belong to each category.  Each
896 category table defines its own categories, but normally these are
897 initialized by copying from the standard categories table, so that the
898 standard categories are available in all modes.
900   Each category has a name, which is an @sc{ascii} printing character in
901 the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
902 when you define it with @code{define-category}.
904   The category table is actually a char-table (@pxref{Char-Tables}).
905 The element of the category table at index @var{c} is a @dfn{category
906 set}---a bool-vector---that indicates which categories character @var{c}
907 belongs to.  In this category set, if the element at index @var{cat} is
908 @code{t}, that means category @var{cat} is a member of the set, and that
909 character @var{c} belongs to category @var{cat}.
911 @defun define-category char docstring &optional table
912 This function defines a new category, with name @var{char} and
913 documentation @var{docstring}.
915 The new category is defined for category table @var{table}, which
916 defaults to the current buffer's category table.
917 @end defun
919 @defun category-docstring category &optional table
920 This function returns the documentation string of category @var{category}
921 in category table @var{table}.
923 @example
924 (category-docstring ?a)
925      @result{} "ASCII"
926 (category-docstring ?l)
927      @result{} "Latin"
928 @end example
929 @end defun
931 @defun get-unused-category table
932 This function returns a category name (a character) which is not
933 currently defined in @var{table}.  If all possible categories are in use
934 in @var{table}, it returns @code{nil}.
935 @end defun
937 @defun category-table
938 This function returns the current buffer's category table.
939 @end defun
941 @defun category-table-p object
942 This function returns @code{t} if @var{object} is a category table,
943 otherwise @code{nil}.
944 @end defun
946 @defun standard-category-table
947 This function returns the standard category table.
948 @end defun
950 @defun copy-category-table &optional table
951 This function constructs a copy of @var{table} and returns it.  If
952 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
953 current category table.  Otherwise, an error is signaled if @var{table}
954 is not a category table.
955 @end defun
957 @defun set-category-table table
958 This function makes @var{table} the category table for the current
959 buffer.  It returns @var{table}.
960 @end defun
962 @defun make-category-table
963 @tindex make-category-table
964 This creates and returns an empty category table.  In an empty category
965 table, no categories have been allocated, and no characters belong to
966 any categories.
967 @end defun
969 @defun make-category-set categories
970 This function returns a new category set---a bool-vector---whose initial
971 contents are the categories listed in the string @var{categories}.  The
972 elements of @var{categories} should be category names; the new category
973 set has @code{t} for each of those categories, and @code{nil} for all
974 other categories.
976 @example
977 (make-category-set "al")
978      @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
979 @end example
980 @end defun
982 @defun char-category-set char
983 This function returns the category set for character @var{char}.  This
984 is the bool-vector which records which categories the character
985 @var{char} belongs to.  The function @code{char-category-set} does not
986 allocate storage, because it returns the same bool-vector that exists in
987 the category table.
989 @example
990 (char-category-set ?a)
991      @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
992 @end example
993 @end defun
995 @defun category-set-mnemonics category-set
996 This function converts the category set @var{category-set} into a string
997 containing the characters that designate the categories that are members
998 of the set.
1000 @example
1001 (category-set-mnemonics (char-category-set ?a))
1002      @result{} "al"
1003 @end example
1004 @end defun
1006 @defun modify-category-entry character category &optional table reset
1007 This function modifies the category set of @var{character} in category
1008 table @var{table} (which defaults to the current buffer's category
1009 table).
1011 Normally, it modifies the category set by adding @var{category} to it.
1012 But if @var{reset} is non-@code{nil}, then it deletes @var{category}
1013 instead.
1014 @end defun