GNU Info

(elisp)Parsing Expressions

---

Next: Standard Syntax Tables Prev: Motion and Syntax Up: Syntax Tables

---

Enter node , (file) or (file)node

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.  Note: 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
     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.  If STOP-COMMENT is the symbol `syntax-table',
     parsing stops after the start of a comment or a string, or the end
     of a comment or a string, whichever comes first.

     The fifth argument STATE is a nine-element list of the same form
     as the value of this function, described below.  (It is OK to omit
     the last element of the nine.)  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 nine elements describing the final state of
     the parse:

       0. The depth in parentheses, counting from 0.

       1. The character position of the start of the innermost
          parenthetical grouping containing the stopping point; `nil'
          if none.

       2. The character position of the start of the last complete
          subexpression terminated; `nil' if none.

       3. Non-`nil' if inside a string.  More precisely, this is the
          character that will terminate the string, or `t' if a generic
          string delimiter character should terminate it.

       4. `t' if inside a comment (of either style), or the comment
          nesting level if inside a kind of comment that can be nested.

       5. `t' if point is just after a quote character.

       6. The minimum parenthesis depth encountered during this scan.

       7. What kind of comment is active: `nil' for a comment of style
          "a", `t' for a comment of style "b", and `syntax-table' for a
          comment that should be ended by a generic comment delimiter
          character.

       8. The string or comment start position.  While inside a
          comment, this is the position where the comment began; while
          inside a string, this is the position where the string began.
          When outside of strings and comments, this element is `nil'.

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

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

 - Variable: multibyte-syntax-as-symbol
     If this variable is non-`nil', `scan-sexps' treats all non-ASCII
     characters as symbol constituents regardless of what the syntax
     table says about them.  (However, text properties can still
     override the syntax.)

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

   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.