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