[Emacs-diffs] Changes to emacs/lispref/syntax.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/12/17 22:02:34

Index: syntax.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/syntax.texi,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -b -r1.53 -r1.54
--- syntax.texi 18 Jul 2006 00:06:43 -0000      1.53
+++ syntax.texi 17 Dec 2006 22:02:34 -0000      1.54
@@ -597,26 +597,26 @@
 @end defun
 
 @node Parsing Expressions
address@hidden Parsing Balanced Expressions
address@hidden Parsing Expressions
 
-  Here are several functions for parsing and scanning balanced
+  This section describes functions for parsing and scanning balanced
 expressions, also known as @dfn{sexps}.  Basically, a sexp is either a
-balanced parenthetical grouping, or a symbol name (a sequence of
-characters whose syntax is either word constituent or symbol
-constituent).  However, characters whose syntax is expression prefix
-are treated as part of the sexp if they appear next to it.
+balanced parenthetical grouping, a string, or a symbol name (a
+sequence of characters whose syntax is either word constituent or
+symbol constituent).  However, characters whose syntax is expression
+prefix are treated as part of the sexp if they appear next to it.
 
   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.  @xref{List Motion}, for convenient
 higher-level functions for moving over balanced expressions.
 
-  A syntax table only describes how each character changes the state
-of the parser, rather than describing the state itself.  For example,
-a string delimiter character toggles the parser state between
-``in-string'' and ``in-code'' but the characters inside the string do
-not have any particular syntax to identify them as such.  For example
-(note that 15 is the syntax code for generic string delimiters),
+  A character's syntax controls how it changes the state of the
+parser, rather than describing the state itself.  For example, a
+string delimiter character toggles the parser state between
+``in-string'' and ``in-code,'' but the syntax of characters does not
+directly say whether they are inside a string.  For example (note that
+15 is the syntax code for generic string delimiters),
 
 @example
 (put-text-property 1 9 'syntax-table '(15 . nil))
@@ -627,46 +627,128 @@
 are a string, but rather that they are all string delimiters.  As a
 result, Emacs treats them as four consecutive empty string constants.
 
-  Every time you use the parser, you specify it a starting state as
-well as a starting position.  If you omit the starting state, the
-default is ``top level in parenthesis structure,'' as it would be at
-the beginning of a function definition.  (This is the case for
address@hidden, which blindly assumes that the starting point is
-in such a state.)
address@hidden
+* Motion via Parsing::       Motion functions that work by parsing.
+* Position Parse::           Determining the syntactic state of a position.
+* Parser State::             How Emacs represents a syntactic state.
+* Low-Level Parsing::        Parsing across a specified region.
+* Control Parsing::          Parameters that affect parsing.
address@hidden menu
 
address@hidden parse-partial-sexp start limit &optional target-depth 
stop-before state stop-comment
-This function parses a sexp in the current buffer starting at
address@hidden, not scanning past @var{limit}.  It stops at position
address@hidden 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.
address@hidden Motion via Parsing
address@hidden Motion Commands Based on Parsing
 
-If @var{state} is @code{nil}, @var{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 @var{state}
-argument that describes the initial status of parsing.
+  This section describes simple point-motion functions that operate
+based on parsing expressions.
 
address@hidden parenthesis depth
-If the third argument @var{target-depth} is address@hidden, parsing
-stops if the depth in parentheses becomes equal to @var{target-depth}.
-The depth starts at 0, or at whatever is given in @var{state}.
address@hidden 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 the fourth argument @var{stop-before} is address@hidden, parsing
-stops when it comes to any character that starts a sexp.  If
address@hidden is address@hidden, parsing stops when it comes to the
-start of a comment.  If @var{stop-comment} is the symbol
address@hidden, parsing stops after the start of a comment or a
-string, or the end of a comment or a string, whichever comes first.
+If @var{depth} is nonzero, parenthesis depth counting begins from that
+value.  The only candidates for stopping are places where the depth in
+parentheses becomes zero; @code{scan-lists} counts @var{count} such
+places and then stops.  Thus, a positive value for @var{depth} means go
+out @var{depth} levels of parenthesis.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
address@hidden
+
+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.
address@hidden defun
+
address@hidden scan-sexps from count
+This function scans forward @var{count} sexps from position @var{from}.
+It returns the position where the scan stops.  If @var{count} is
+negative, the scan moves backwards.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
address@hidden
+
+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, @code{nil} is returned.
address@hidden defun
+
address@hidden forward-comment count
+This function moves point forward across @var{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 @var{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 @var{count} comments are found as
+expected, with nothing except whitespace between them, it returns
address@hidden; otherwise it returns @code{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.
address@hidden defun
+
+To move forward over all comments and whitespace following point, use
address@hidden(forward-comment (buffer-size))}.  @code{(buffer-size)} is a good
+argument to use, because the number of comments in the buffer cannot
+exceed that many.
+
address@hidden Position Parse
address@hidden Finding the Parse State for a Position
+
+  For syntactic analysis, such as in indentation, often the useful
+thing is to compute the syntactic state corresponding to a given buffer
+position.  This function does that conveniently.
 
address@hidden parse state
-The fifth argument @var{state} is a ten-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 @code{parse-partial-sexp}.
address@hidden syntax-ppss &optional pos
+This function returns the parser state (see next section) that the
+parser would reach at position @var{pos} starting from the beginning
+of the buffer.  This is equivalent to @code{(parse-partial-sexp
+(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache
+to speed up the computation.  Due to this optimization, the 2nd value
+(previous complete subexpression) and 6th value (minimum parenthesis
+depth) of the returned parser state are not meaningful.
address@hidden defun
 
-The result is a list of ten elements describing the final state of
-the parse:
+   @code{syntax-ppss} automatically hooks itself to
address@hidden to keep its cache consistent.  But
+updating can fail if @code{syntax-ppss} is called while
address@hidden is temporarily let-bound, or if the
+buffer is modified without obeying the hook, such as when using
address@hidden  For this reason, it is sometimes
+necessary to flush the cache manually.
+
address@hidden syntax-ppss-flush-cache beg
+This function flushes the cache used by @code{syntax-ppss}, starting at
+position @var{beg}.
address@hidden defun
+
+  Major modes can make @code{syntax-ppss} run faster by specifying
+where it needs to start parsing.
+
address@hidden syntax-begin-function
+If this is address@hidden, it should be a function that moves to an
+earlier buffer position where the parser state is equivalent to
address@hidden other words, a position outside of any comment,
+string, or parenthesis.  @code{syntax-ppss} uses it to further
+optimize its computations, when the cache gives no help.
address@hidden defvar
+
address@hidden Parser State
address@hidden Parser State
address@hidden parser state
+
+  A @dfn{parser state} is a list of ten elements describing the final
+state of parsing text syntactically as part of an expression.  The
+parsing functions in the following sections return a parser state as
+the value, and in some cases accept one as an argument also, so that
+you can resume parsing after it stops.  Here are the meanings of the
+elements of the parser state:
 
 @enumerate 0
 @item
@@ -721,81 +803,65 @@
 as the @var{state} argument to another call.
 @end enumerate
 
-Elements 1, 2, and 6 are ignored in the argument @var{state}.  Element
-8 is used only to set the corresponding element of the return value,
-in certain simple cases.  Element 9 is used only to set element 1 of
-the return value, in trivial cases where parsing starts and stops
-within the same pair of parentheses.
-
address@hidden indenting with parentheses
-This function is most often used to compute indentation for languages
-that have nested parentheses.
address@hidden defun
-
address@hidden syntax-ppss &optional pos
-This function returns the state that the parser would have at position
address@hidden, if it were started with a default start state at the
-beginning of the buffer.  Thus, it is equivalent to
address@hidden(parse-partial-sexp (point-min) @var{pos})}, except that
address@hidden uses a cache to speed up the computation.  Also,
-the 2nd value (previous complete subexpression) and 6th value (minimum
-parenthesis depth) of the returned state are not meaningful.
address@hidden defun
-
address@hidden syntax-ppss-flush-cache beg
-This function flushes the cache used by @code{syntax-ppss}, starting at
-position @var{beg}.
+  Elements 1, 2, and 6 are ignored in a state which you pass as an
+argument to continue parsing, and elements 8 and 9 are used only in
+trivial cases.  Those elements serve primarily to convey information
+to the Lisp program which does the parsing.
+
+  One additional piece of useful information is available from a
+parser state using this function:
+
address@hidden syntax-ppss-toplevel-pos state
+This function extracts, from parser state @var{state}, the last
+position scanned in the parse which was at top level in grammatical
+structure.  ``At top level'' means outside of any parentheses,
+comments, or strings.
+
+The value is @code{nil} if @var{state} represents a parse which has
+arrived at a top level position.
address@hidden defun
+
+  We have provided this access function rather than document how the
+data is represented in the state, because we plan to change the
+representation in the future.
+
address@hidden Low-Level Parsing
address@hidden Low-Level Parsing
+
+  The most basic way to use the expression parser is to tell it
+to start at a given position with a certain state, and parse up to
+a specified end position.
 
-When @code{syntax-ppss} is called, it automatically hooks itself
-to @code{before-change-functions} to keep its cache consistent.
-But this can fail if @code{syntax-ppss} is called while
address@hidden is temporarily let-bound, or if the
-buffer is modified without obeying the hook, such as when using
address@hidden  For this reason, it is sometimes
-necessary to flush the cache manually.
address@hidden defun
-
address@hidden syntax-begin-function
-If this is address@hidden, it should be a function that moves to an
-earlier buffer position where the parser state is equivalent to
address@hidden other words, a position outside of any comment,
-string, or parenthesis.  @code{syntax-ppss} uses it to supplement its
-cache.
address@hidden defvar
-
address@hidden 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.
address@hidden parse-partial-sexp start limit &optional target-depth 
stop-before state stop-comment
+This function parses a sexp in the current buffer starting at
address@hidden, not scanning past @var{limit}.  It stops at position
address@hidden or when certain criteria described below are met, and sets
+point to the location where parsing stops.  It returns a parser state
+describing the status of the parse at the point where it stops.
 
-If @var{depth} is nonzero, parenthesis depth counting begins from that
-value.  The only candidates for stopping are places where the depth in
-parentheses becomes zero; @code{scan-lists} counts @var{count} such
-places and then stops.  Thus, a positive value for @var{depth} means go
-out @var{depth} levels of parenthesis.
address@hidden parenthesis depth
+If the third argument @var{target-depth} is address@hidden, parsing
+stops if the depth in parentheses becomes equal to @var{target-depth}.
+The depth starts at 0, or at whatever is given in @var{state}.
 
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
address@hidden
+If the fourth argument @var{stop-before} is address@hidden, parsing
+stops when it comes to any character that starts a sexp.  If
address@hidden is address@hidden, parsing stops when it comes to the
+start of a comment.  If @var{stop-comment} is the symbol
address@hidden, parsing stops after the start of a comment or a
+string, or the end of a comment or a string, whichever comes first.
 
-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 @var{state} is @code{nil}, @var{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 @var{state}
+argument that describes the initial status of parsing.  The value
+returned by a previous call to @code{parse-partial-sexp} will do
+nicely.
 @end defun
 
address@hidden scan-sexps from count
-This function scans forward @var{count} sexps from position @var{from}.
-It returns the position where the scan stops.  If @var{count} is
-negative, the scan moves backwards.
-
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
address@hidden
-
-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, @code{nil} is returned.
address@hidden defun
address@hidden Control Parsing
address@hidden Parameters to Control Parsing
 
 @defvar multibyte-syntax-as-symbol
 If this variable is address@hidden, @code{scan-sexps} treats all
@@ -817,29 +883,6 @@
 You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
 
address@hidden forward-comment count
-This function moves point forward across @var{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 @var{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 @var{count} comments are found as
-expected, with nothing except whitespace between them, it returns
address@hidden; otherwise it returns @code{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.
address@hidden defun
-
-To move forward over all comments and whitespace following point, use
address@hidden(forward-comment (buffer-size))}.  @code{(buffer-size)} is a good
-argument to use, because the number of comments in the buffer cannot
-exceed that many.
-
 @node Standard Syntax Tables
 @section Some Standard Syntax Tables