45.5 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 List Motion, for convenient higher-level functions for moving over balanced expressions.

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

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.

The fifth argument state is an eight-element list of the same form as the value of this function, described below. 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 eight 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.
5. t if inside a comment (of either style).
6. t if point is just after a quote character.
7. The minimum parenthesis depth encountered during this scan.
8. t if inside a comment of style “b”.

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 &optional buffer noerror

This function scans forward count balanced parenthetical groupings from character number from. It returns the character position where the scan stops.

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.

If optional arg buffer is non-nil, scanning occurs in that buffer instead of in the current buffer.

If optional arg noerror is non-nil, scan-lists will return nil instead of signalling an error.

Function: scan-sexps from count &optional buffer noerror

This function scans forward count sexps from character position from. It returns the character position where the scan stops.

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 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.

If optional arg buffer is non-nil, scanning occurs in that buffer instead of in the current buffer.

If optional arg noerror is non-nil, scan-sexps will return nil instead of signalling an error.

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 &optional count buffer

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. count defaults to 1.

Optional argument buffer defaults to the current buffer.

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.