elisp: Motion via Parsing
34.6.1 Motion Commands Based on Parsing
---------------------------------------
This section describes simple point-motion functions that operate based
on parsing expressions.
-- 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, treat the starting position as being DEPTH
parentheses deep. The scanner moves forward or backward through
the buffer until the depth changes to zero COUNT times. Hence, a
positive value for DEPTH has the effect of moving out DEPTH levels
of parenthesis from the starting position, while a negative DEPTH
has the effect of moving deeper by -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 accessible part of
the buffer before it has scanned over COUNT parenthetical
groupings, the return value is ‘nil’ if the depth at that point is
zero; if the depth is non-zero, a ‘scan-error’ error is signaled.
-- 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.
-- Function: forward-comment count
This function moves point forward across COUNT complete comments
(that is, including the starting delimiter and the terminating
delimiter if any), plus any whitespace encountered on the way. It
moves backward if COUNT is negative. If it encounters anything
other than a comment or whitespace, it stops, leaving point at the
place where it stopped. This includes (for instance) finding the
end of a comment when moving forward and expecting the beginning of
one. The function also stops immediately after moving over the
specified number of complete comments. If COUNT comments are found
as expected, with nothing except whitespace between them, it
returns ‘t’; otherwise it returns ‘nil’.
This function cannot tell whether the comments it traverses are
embedded within a string. If they look like comments, it treats
them as comments.
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.
Info Catalog
elisp: Parsing Expressions
elisp: Position Parse