A parser state is a list of (currently) eleven elements describing the state of the syntactic parser, after it parses the text between a specified starting point and a specified end point in the buffer using
parse-partial-sexp (see Low-Level Parsing). Parsing functions such as
syntax-ppss (see Position Parse) also return a parser state as the value.
parse-partial-sexp can accept a parser state as an argument, for resuming parsing.
Here are the meanings of the elements of the parser state:
- The depth in parentheses, counting from 0. Warning: this can be negative if there are more close parens than open parens between the parser’s starting point and end point.
- The character position of the start of the innermost parenthetical grouping containing the stopping point;
- The character position of the start of the last complete subexpression terminated;
nilif inside a string. More precisely, this is the character that will terminate the string, or
tif a generic string delimiter character should terminate it.
tif inside a non-nestable comment (of any comment style; see Syntax Flags); or the comment nesting level if inside a comment that can be nested.
tif the end point is just after a quote character.
- The minimum parenthesis depth encountered during this scan.
- What kind of comment is active:
nilif not in a comment or in a comment of style ‘
a’; 1 for a comment of style ‘
b’; 2 for a comment of style ‘
syntax-tablefor a comment that should be ended by a generic comment delimiter character.
- 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
- The list of the positions of the currently open parentheses, starting with the outermost.
- When the last buffer position scanned was the (potential) first character of a two character construct (comment delimiter or escaped/char-quoted character pair), the
syntax-code(see Syntax Table Internals) of that position. Otherwise
Elements 1, 2, and 6 are ignored in a state which you pass as an argument to
parse-partial-sexp to continue parsing. Elements 9 and 10 are mainly used internally by the parser code.
Some additional useful information is available from a parser state using these functions:
function syntax-ppss-toplevel-pos state
This function extracts, from parser state
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
state represents a parse which has arrived at a top level position.
function syntax-ppss-context state
string if the end position of the scan returning
state is in a string, and
comment if it’s in a comment.