Subject: Re: bug#32504: [PATCH] syntax-is-{comment|string}-p

From: Noam Postavsky <[email-masked]>
Date: Mon, 08 Jul 2019 20:05:15 -0400

Alex Branham <[email-masked]> writes:

> On Thu 30 Aug 2018 at 20:21, Noam Postavsky <[email-masked]> wrote:
>
>>> I'm not a big fan of the docstrings generated by this, is there a way to
>>> change them to be more helpful?
>>
>> Hmm, doesn't look like it.  Well, that's just a convenient way of
>> defining them all quickly for discussion, it wouldn't be that much
>> harder to write out defuns I guess.
>
> Fair enough.

The recent talk about accessors for decoded time reminded me of this.
Here's an initial patch.

>From 0d09658a33aed36b0b647dc8dbfd08d8aa2dc535 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <[email-masked]>
Date: Mon, 8 Jul 2019 18:45:53 -0400
Subject: [PATCH] Add named accessors for syntax-ppss state (Bug#32504)

* lisp/emacs-lisp/syntax.el (syntax-ppss-depth, syntax-ppss-list-start)
(syntax-ppss-last-sexp-start, syntax-ppss-string-terminator)
(syntax-ppss-comment, syntax-ppss-quoted-p, syntax-ppss-min-depth)
(syntax-ppss-comment-style, syntax-ppss-context-start)
(syntax-ppss-open-parens, syntax-ppss-syntax-sequence): New functions.
(syntax-ppss-toplevel-pos, syntax-ppss-context): Use them.
---
 lisp/emacs-lisp/syntax.el | 62 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 58 insertions(+), 4 deletions(-)

diff --git a/lisp/emacs-lisp/syntax.el b/lisp/emacs-lisp/syntax.el
index 6464e2a52d..b7a5e585b7 100644
--- a/lisp/emacs-lisp/syntax.el
+++ b/lisp/emacs-lisp/syntax.el
@@ -358,7 +358,61 @@ internal--syntax-propertize
 ;;; Incrementally compute and memoize parser state.
 
 (defsubst syntax-ppss-depth (ppss)
+  "Depth in parens according to PPSS.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
   (nth 0 ppss))
+(defsubst syntax-ppss-list-start (ppss)
+  "Start of innermost containing list according to PPSS; nil if none.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 1 ppss))
+(defsubst syntax-ppss-last-sexp-start (ppss)
+  "Start of last complete sexp terminated according to PPSS.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 2 ppss))
+(defsubst syntax-ppss-string-terminator (ppss)
+  "Terminating character of current string according to PPSS.
+Return t if the string should be terminated by generic string
+delimiter, or nil if not in a string.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 3 ppss))
+(defsubst syntax-ppss-comment (ppss)
+  "Non-nil if inside a comment according to PPSS.
+Return t if inside a non-nestable comment, else an integer (the comment
+nesting depth).
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 4 ppss))
+(defsubst syntax-ppss-quoted-p (ppss)
+  "Non-nil if PPSS points to a position following a quote.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 5 ppss))
+(defsubst syntax-ppss-min-depth (ppss)
+  "Minimum parenthesis depth of the scan according to PPSS.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 6 ppss))
+(defsubst syntax-ppss-comment-style (ppss)
+  ;; FIXME: What is comment style exactly?
+  "Comment style according to PPSS.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 7 ppss))
+(defsubst syntax-ppss-context-start (ppss)
+  "Start of comment or string according to PPSS.
+Return nil if not in one.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 8 ppss))
+(defsubst syntax-ppss-open-parens (ppss)
+  "List of open parens according to PPSS.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 9 ppss))
+(defsubst syntax-ppss-syntax-sequence (ppss)
+  "Syntax of the 1st of a two character sequence according to PPSS.
+When the last position scanned holds the first character of a
+\(potential) two character construct, the syntax of that
+position, otherwise nil.  That construct can be a two character
+comment delimiter or an Escaped or Char-quoted character.
+PPSS is the return value `parse-partial-sexp' or `syntax-ppss'."
+  (nth 10 ppss))
+
+
 
 (defun syntax-ppss-toplevel-pos (ppss)
   "Get the latest syntactically outermost position found in a syntactic scan.
@@ -367,8 +421,8 @@ syntax-ppss-toplevel-pos
 outside of any parentheses, comments, or strings encountered in the scan.
 If no such position is recorded in PPSS (because the end of the scan was
 itself at the outermost level), return nil."
-  (or (car (nth 9 ppss))
-      (nth 8 ppss)))
+  (or (car (syntax-ppss-open-parens ppss))
+      (syntax-ppss-context-start ppss)))
 
 (defsubst syntax-ppss-context (ppss)
   "Say whether PPSS is a string, a comment, or something else.
@@ -376,8 +430,8 @@ syntax-ppss-context
 comment, the symbol `comment' is returned.  If it's something
 else, nil is returned."
   (cond
-   ((nth 3 ppss) 'string)
-   ((nth 4 ppss) 'comment)
+   ((syntax-ppss-string-terminator ppss) 'string)
+   ((syntax-ppss-comment ppss) 'comment)
    (t nil)))
 
 (defvar syntax-ppss-max-span 20000
-- 
2.11.0

>>> CL-X defaults to point.
>>
>> And, my intention is to operate on the return value of syntax-ppss, not
>> give a point to call it with.
>
> Right, but whenever I want to call on these functions, 90% of the time
> the question I'm trying to answer is "Is point in a comment/string?" And
> the 3rd party ***-is-comment/string-p functions I've looked at usually
> (always?) look at positions.

Well, for me I just want to stop having to look up the docstring of
parse-partial-sexp every damn time I see (nth X PPSS).  But I wouldn't
be against having syntax-is-comment/string-p which take a position as
well.