35.6 Parsing Balanced Expressions

Here are several functions for parsing and scanning balanced expressions, also known as sexps, in which parentheses match in pairs. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. See section 30.2.6 Moving over Balanced Expressions, for convenient higher-level functions for moving over balanced expressions.

Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment

This function parses a sexp in the current buffer starting at start, not scanning past limit. It stops at position limit or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a value describing the status of the parse at the point where it stops.

If state is nil, start is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a state argument that describes the initial status of parsing.

If the third argument target-depth is non-nil, parsing stops if the depth in parentheses becomes equal to target-depth. The depth starts at 0, or at whatever is given in state.

If the fourth argument stop-before is non-nil, parsing stops when it comes to any character that starts a sexp. If stop-comment is non-nil, parsing stops when it comes to the start of a comment. If stop-comment is the symbol 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.

The fifth argument state is a nine-element list of the same form as the value of this function, described below. (It is OK to omit the last element of the nine.) The return value of one call may be used to initialize the state of the parse on another call to parse-partial-sexp.

The result is a list of nine elements describing the final state of the parse:

1. The depth in parentheses, counting from 0.

2. The character position of the start of the innermost parenthetical grouping containing the stopping point; nil if none.

3. The character position of the start of the last complete subexpression terminated; nil if none.

4. Non-nil if inside a string. More precisely, this is the character that will terminate the string, or t if a generic string delimiter character should terminate it.

5. t if inside a comment (of either style), or the comment nesting level if inside a kind of comment that can be nested.

6. t if point is just after a quote character.

7. The minimum parenthesis depth encountered during this scan.

8. What kind of comment is active: nil for a comment of style "a", t for a comment of style "b", and syntax-table for a comment that should be ended by a generic comment delimiter character.

9. The string or comment start position. While inside a comment, this is the position where the comment began; while inside a string, this is the position where the string began. When outside of strings and comments, this element is nil.

Elements 0, 3, 4, 5 and 7 are significant in the argument state.

This function is most often used to compute indentation for languages that have nested parentheses.

Function: scan-lists from count depth

This function scans forward count balanced parenthetical groupings from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

If depth is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; scan-lists counts count such places and then stops. Thus, a positive value for depth means go out depth levels of parenthesis.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, nil is returned.

Function: scan-sexps from count

This function scans forward count sexps from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of (the accessible part of) the buffer while in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, nil is returned.

Variable: multibyte-syntax-as-symbol

If this variable is non-nil, scan-sexps treats all non-ASCII characters as symbol constituents regardless of what the syntax table says about them. (However, text properties can still override the syntax.)

Variable: parse-sexp-ignore-comments

If the value is non-nil, then comments are treated as whitespace by the functions in this section and by forward-sexp.

In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable nil, since not every newline is the end of a comment. This limitation no longer exists.

You can use forward-comment to move forward or backward over one comment or several comments.

Function: forward-comment count

This function moves point forward across count comments (backward, if count is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying count.

To move forward over all comments and whitespace following point, use (forward-comment (buffer-size)). (buffer-size) is a good argument to use, because the number of comments in the buffer cannot exceed that many.