@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Syntax Tables
Usually, this designator character is one that is often assigned that
class; however, its meaning as a designator is unvarying and
independent of what syntax that character currently has. Thus,
-@samp{\} as a designator character always means ``escape character''
+@samp{\} as a designator character always stands for escape character
syntax, regardless of whether the @samp{\} character actually has that
syntax in the current syntax table.
@ifnottex
The Lisp modes have two string quote characters: double-quote (@samp{"})
and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it
is used in Common Lisp. C also has two string quote characters:
-double-quote for strings, and single-quote (@samp{'}) for character
+double-quote for strings, and apostrophe (@samp{'}) for character
constants.
Human text has no string quote characters. We do not want quotation
delimiter, @samp{c} on either character makes it of style ``c''.
@item
-@samp{n} on a comment delimiter character specifies
-that this kind of comment can be nested. For a two-character
-comment delimiter, @samp{n} on either character makes it
-nestable.
+@samp{n} on a comment delimiter character specifies that this kind of
+comment can be nested. Inside such a comment, only comments of the
+same style will be recognized. For a two-character comment delimiter,
+@samp{n} on either character makes it nestable.
@cindex comment style
Emacs supports several comment styles simultaneously in any one syntax
@end table
@item
-@samp{p} identifies an additional ``prefix character'' for Lisp syntax.
+@samp{p} identifies an additional prefix character for Lisp syntax.
These characters are treated as whitespace when they appear between
expressions. When they appear within an expression, they are handled
according to their usual syntax classes.
@node Motion and Syntax
@section Motion and Syntax
+@cindex moving across syntax classes
+@cindex skipping characters of certain syntax
This section describes functions for moving across characters that
have certain syntax classes.
@node Parsing Expressions
@section Parsing Expressions
+@cindex parsing expressions
+@cindex scanning expressions
This section describes functions for parsing and scanning balanced
expressions. We will refer to such expressions as @dfn{sexps},
following the terminology of Lisp, even though these functions can act
on languages other than Lisp. Basically, a sexp is either a balanced
-parenthetical grouping, a string, or a ``symbol'' (i.e., a sequence
+parenthetical grouping, a string, or a symbol (i.e., a sequence
of characters whose syntax is either word constituent or symbol
constituent). However, characters in the expression prefix syntax
class (@pxref{Syntax Class Table}) are treated as part of the sexp if
A character's syntax controls how it changes the state of the
parser, rather than describing the state itself. For example, a
string delimiter character toggles the parser state between
-``in-string'' and ``in-code'', but the syntax of characters does not
+in-string and in-code, but the syntax of characters does not
directly say whether they are inside a string. For example (note that
15 is the syntax code for generic string delimiters),
@node Motion via Parsing
@subsection Motion Commands Based on Parsing
+@cindex motion based on parsing
This section describes simple point-motion functions that operate
based on parsing expressions.
expected, with nothing except whitespace between them, it returns
@code{t}; otherwise it returns @code{nil}.
-This function cannot tell whether the ``comments'' it traverses are
+This function cannot tell whether the comments it traverses are
embedded within a string. If they look like comments, it treats them
as comments.
@node Position Parse
@subsection Finding the Parse State for a Position
+@cindex parse state for a position
For syntactic analysis, such as in indentation, often the useful
thing is to compute the syntactic state corresponding to a given buffer
Hooks}).
@end defun
- Major modes can make @code{syntax-ppss} run faster by specifying
-where it needs to start parsing.
-
-@defvar syntax-begin-function
-If this is non-@code{nil}, it should be a function that moves to an
-earlier buffer position where the parser state is equivalent to
-@code{nil}---in other words, a position outside of any comment,
-string, or parenthesis. @code{syntax-ppss} uses it to further
-optimize its computations, when the cache gives no help.
-@end defvar
-
@node Parser State
@subsection Parser State
@cindex parser state
- A @dfn{parser state} is a list of ten elements describing the state
-of the syntactic parser, after it parses the text between a specified
-starting point and a specified end point in the buffer. Parsing
-functions such as @code{syntax-ppss}
+ A @dfn{parser state} is a list of (currently) eleven elements
+describing the state of the syntactic parser, after it parses the text
+between a specified starting point and a specified end point in the
+buffer. Parsing functions such as @code{syntax-ppss}
@ifnottex
(@pxref{Position Parse})
@end ifnottex
this element is @code{nil}.
@item
-Internal data for continuing the parsing. The meaning of this
-data is subject to change; it is used if you pass this list
-as the @var{state} argument to another call.
+The list of the positions of the currently open parentheses, starting
+with the outermost.
+
+@item
+When the last buffer position scanned was the (potential) first
+character of a two character construct (comment delimiter or
+escaped/char-quoted character pair), the @var{syntax-code}
+(@pxref{Syntax Table Internals}) of that position. Otherwise
+@code{nil}.
@end enumerate
Elements 1, 2, and 6 are ignored in a state which you pass as an
-argument to continue parsing, and elements 8 and 9 are used only in
-trivial cases. Those elements are mainly used internally by the
-parser code.
+argument to continue parsing. Elements 9 and 10 are mainly used
+internally by the parser code.
One additional piece of useful information is available from a
parser state using this function:
If the fourth argument @var{stop-before} is non-@code{nil}, parsing
stops when it comes to any character that starts a sexp. If
-@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
-start of a comment. If @var{stop-comment} is the symbol
-@code{syntax-table}, parsing stops after the start of a comment or a
-string, or the end of a comment or a string, whichever comes first.
+@var{stop-comment} is non-@code{nil}, parsing stops after the start of
+an unnested comment. If @var{stop-comment} is the symbol
+@code{syntax-table}, parsing stops after the start of an unnested
+comment or a string, or after the end of an unnested comment or a
+string, whichever comes first.
If @var{state} is @code{nil}, @var{start} is assumed to be at the top
level of parenthesis structure, such as the beginning of a function
@node Control Parsing
@subsection Parameters to Control Parsing
+@cindex parsing, control parameters
@defvar multibyte-syntax-as-symbol
If this variable is non-@code{nil}, @code{scan-sexps} treats all
The behavior of @code{parse-partial-sexp} is also affected by
@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
+@defvar comment-end-can-be-escaped
+If this buffer local variable is non-@code{nil}, a single character
+which usually terminates a comment doesn't do so when that character
+is escaped. This is used in C and C++ Modes, where line comments
+starting with @samp{//} can be continued onto the next line by
+escaping the newline with @samp{\}.
+@end defvar
+
You can use @code{forward-comment} to move forward or backward over
one comment or several comments.
Here's an example of defining a new category for characters that have
strong right-to-left directionality (@pxref{Bidirectional Display})
-and using it in a special category table:
+and using it in a special category table. To obtain the information
+about the directionality of characters, the example code uses the
+@samp{bidi-class} Unicode property (@pxref{Character Properties,
+bidi-class}).
@example
(defvar special-category-table-for-bidi
+ ;; Make an empty category-table.
(let ((category-table (make-category-table))
- (uniprop-table (unicode-property-table-internal 'bidi-class)))
+ ;; Create a char-table which gives the 'bidi-class' Unicode
+ ;; property for each character.
+ (uniprop-table (unicode-property-table-internal 'bidi-class)))
(define-category ?R "Characters of bidi-class R, AL, or RLO"
category-table)
+ ;; Modify the category entry of each character whose 'bidi-class'
+ ;; Unicode property is R, AL, or RLO -- these have a
+ ;; right-to-left directionality.
(map-char-table
#'(lambda (key val)
- (if (memq val '(R AL RLO))
- (modify-category-entry key ?R category-table)))
+ (if (memq val '(R AL RLO))
+ (modify-category-entry key ?R category-table)))
uniprop-table)
category-table))
@end example