Commit 7b926f3f authored by Chong Yidong's avatar Chong Yidong

Clarify doc of scan-lists.

* doc/lispref/syntax.texi (Motion via Parsing): Doc fix for scan-lists.

* src/syntax.c (Fscan_lists): Doc fix.

Fixes: debbugs:10833
parent ee0ce425
2012-02-17 Chong Yidong <cyd@gnu.org>
* syntax.texi (Motion via Parsing): Doc fix for scan-lists.
2012-02-17 Glenn Morris <rgm@gnu.org>
* hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual.
......
......@@ -646,25 +646,25 @@ result, Emacs treats them as four consecutive empty string constants.
based on parsing expressions.
@defun scan-lists from count depth
This function scans forward @var{count} balanced parenthetical groupings
from position @var{from}. It returns the position where the scan stops.
If @var{count} is negative, the scan moves backwards.
If @var{depth} is nonzero, assume that the starting point is already
@var{depth} parentheses deep. This function counts out @var{count}
number of points where the parenthesis depth goes back to zero, then
stops. Thus, a positive value for @var{depth} has the effect of
moving out @var{depth} levels of parenthesis, whereas a negative
@var{depth} has the effect of moving deeper by @var{-depth} levels of
parenthesis.
This function scans forward @var{count} balanced parenthetical
groupings from position @var{from}. It returns the position where the
scan stops. If @var{count} is negative, the scan moves backwards.
If @var{depth} is nonzero, treat the starting position as being
@var{depth} parentheses deep. The scanner moves forward or backward
through the buffer until the depth changes to zero @var{count} times.
Hence, a positive value for @var{depth} has the effect of moving out
@var{depth} levels of parenthesis from the starting position, while a
negative @var{depth} has the effect of moving deeper by @var{-depth}
levels of parenthesis.
Scanning ignores comments if @code{parse-sexp-ignore-comments} is
non-@code{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, @code{nil} is
returned.
If the scan reaches the beginning or end of the accessible part of the
buffer before it has scanned over @var{count} parenthetical groupings,
the return value is @code{nil} if the depth at that point is zero; if
the depth is non-zero, a @code{scan-error} error is signaled.
@end defun
@defun scan-sexps from count
......
2012-02-17 Chong Yidong <cyd@gnu.org>
* syntax.c (Fscan_lists): Doc fix (Bug#10833).
2012-02-15 Paul Eggert <eggert@cs.ucla.edu>
* image.c (MAX_IMAGE_SIZE): Increase from 6.0 to 10.0; see
......
......@@ -2844,18 +2844,23 @@ scan_lists (register EMACS_INT from, EMACS_INT count, EMACS_INT depth, int sexpf
DEFUN ("scan-lists", Fscan_lists, Sscan_lists, 3, 3, 0,
doc: /* Scan from character number FROM by COUNT lists.
Returns the character number of the position thus found.
Scan forward if COUNT is positive, backward if COUNT is negative.
Return the character number of the position thus found.
A \"list", in this context, refers to a balanced parenthetical
grouping, as determined by the syntax table.
If DEPTH is nonzero, paren depth begins counting from that value,
only places where the depth in parentheses becomes zero
are candidates for stopping; COUNT such places are counted.
Thus, a positive value for DEPTH means go out levels.
If DEPTH is nonzero, treat that as the nesting depth of the starting
point (i.e. the starting point is DEPTH parentheses deep). This
function scans over parentheses until the depth goes to zero COUNT
times. Hence, positive DEPTH moves out that number of levels of
paretheses, while negative DEPTH moves to a deeper level.
Comments are ignored if `parse-sexp-ignore-comments' is non-nil.
If the beginning or end of (the accessible part of) the buffer is reached
and the depth is wrong, an error is signaled.
If the depth is right but the count is not used up, nil is returned. */)
If we reach the beginning or end of the accessible part of the buffer
before we have scanned over COUNT lists, return nil if the depth at
that point is zero, and signal a error if the depth is nonzero. */)
(Lisp_Object from, Lisp_Object count, Lisp_Object depth)
{
CHECK_NUMBER (from);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment