From: Chong Yidong Date: Fri, 17 Feb 2012 14:01:05 +0000 (+0800) Subject: Clarify doc of scan-lists. X-Git-Tag: emacs-pretest-24.0.94~129 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7b926f3f3db5d9a22260209547fb3e60df919ecf;p=emacs.git 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 --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ab01544c453..85e78abdc32 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2012-02-17 Chong Yidong + + * syntax.texi (Motion via Parsing): Doc fix for scan-lists. + 2012-02-17 Glenn Morris * hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual. diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index dbfa4ca9045..e2fb3238642 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -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 diff --git a/src/ChangeLog b/src/ChangeLog index 12b4fa97c33..7ad28b0473d 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2012-02-17 Chong Yidong + + * syntax.c (Fscan_lists): Doc fix (Bug#10833). + 2012-02-15 Paul Eggert * image.c (MAX_IMAGE_SIZE): Increase from 6.0 to 10.0; see diff --git a/src/syntax.c b/src/syntax.c index bb473a52b3a..645a65f13e6 100644 --- a/src/syntax.c +++ b/src/syntax.c @@ -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);