feature request: public API to get new flymake's errors/warnings

feature request: public API to get new flymake's errors/warnings

[Yuta Yamada]

[-- Attachment #1: Type: text/plain, Size: 819 bytes --]

Hello Emacs devel.

First of all, thank you to rewritten of flymake!

I'm an emacs' package maintainer of flycheck-tip and flycheck-nimsuggest
(nim language's flycheck backend) and I could convert to
flycheck-nimsuggest.el for flymake very easy.

But, as for flycheck-tip (which show flycheck/flymake's errors and warning
on a tooltip), or other
flymake related packages, could you support public API to get errors and
warnings object? (I mean a public function for it)

I think I can implement and extract data if I steal some stuff from
`flymake--diagnostics-buffer-entries', but having public API is better
because I don't feel the fear of devel's change.

just FYI I was using following flymake functions to get the data:

---
(flymake-find-err-info flymake-err-info (line-number-at-pos))
---

Regards,
Yuta Yamada

[-- Attachment #2: Type: text/html, Size: 1086 bytes --]

Re: feature request: public API to get new flymake's errors/warnings

[João Távora]

Yuta Yamada <sleepboy.zzz@gmail.com> writes:

> Hello Emacs devel.
>
> First of all, thank you to rewritten of flymake!
>
> I'm an emacs' package maintainer of flycheck-tip and
> flycheck-nimsuggest (nim language's flycheck backend) and I could
> convert to flycheck-nimsuggest.el for flymake very easy.
>
> But, as for flycheck-tip (which show flycheck/flymake's errors and
> warning on a tooltip), or other flymake related packages, could you
> support public API to get errors and warnings object? (I mean a public
> function for it)
>
I see. I think you could try to write it with the internal functions
that I mention in the rest of this message and then we can more easily
see which parts are currently "internal" that could be "external":

1) Most important you need an easy way to get the the "diagnostic"
object at point. This is held by the overlays within their
'flymake--diagnostic' property.

2) You'll probably need accessors for the flymake--diag object (text,
type, issuing backend function). I think this is a question of renameing
the existing flymake--diag-text, flymake--diag-type,
flymake--diag-backend.

3) Perhaps a way to get all the diagnostics in a region. There is
flymake--overlays for this.

4) Maybe check the properties (severity) of a given type? This is
currently done via flymake--lookup-type-property.

My only doubt is if 1 and 3 should work through the overlays API
(flymake--overlays and overlay-get for discrimination) i.e. If so the
API is smaller, but ties Flymake to an overlay overlay-based
implementation. Otherwise we can make flymake-diagnostics-at-point
etc...

> because I don't feel the fear of devel's change.

:-)

João

Re: feature request: public API to get new flymake's errors/warnings

[Yuta Yamada]

[-- Attachment #1: Type: text/plain, Size: 3665 bytes --]

>
> I see. I think you could try to write it with the internal functions
> that I mention in the rest of this message and then we can more easily
> see which parts are currently "internal" that could be "external":
>
> 1) Most important you need an easy way to get the the "diagnostic"
> object at point. This is held by the overlays within their
> 'flymake--diagnostic' property.
>
> 2) You'll probably need accessors for the flymake--diag object (text,
> type, issuing backend function). I think this is a question of renameing
> the existing flymake--diag-text, flymake--diag-type,
> flymake--diag-backend.
>
> 3) Perhaps a way to get all the diagnostics in a region. There is
> flymake--overlays for this.
>
> 4) Maybe check the properties (severity) of a given type? This is
> currently done via flymake--lookup-type-property.
>

Thank you for your helpful comment.
I've made a function (just for my flymake-tip package) using your comment.

--- code:
(defun flymake-tip-get-diag-text-on-line ()
    "Return list of string of error/warning info on the current line."
    (cl-loop for ov in (flymake--overlays :beg (point-at-bol) :end
(point-at-eol))
             collect (flymake--diag-text (overlay-get ov
'flymake--diagnostic))))
---

As you can see, I used 1 (flymake--overlays), 2 (flymake--diag-text), 3
(flymake--diagnostic).
So, I hope those functions/symbol become public API. (i mean "-" instead of
"--")

Also, after implementing my stuff, I popped up a question:
is there public API to check whether error/warning exists on the buffer?
The reason is I would make a command like flymake-next-error, but if there
is no error
I would invoke other things. (maybe using flymake--overlays to check?)


Thanks,
Yuta Yamada


On Mon, Oct 16, 2017 at 11:23 AM, João Távora <joaotavora@gmail.com> wrote:

> Yuta Yamada <sleepboy.zzz@gmail.com> writes:
>
> > Hello Emacs devel.
> >
> > First of all, thank you to rewritten of flymake!
> >
> > I'm an emacs' package maintainer of flycheck-tip and
> > flycheck-nimsuggest (nim language's flycheck backend) and I could
> > convert to flycheck-nimsuggest.el for flymake very easy.
> >
> > But, as for flycheck-tip (which show flycheck/flymake's errors and
> > warning on a tooltip), or other flymake related packages, could you
> > support public API to get errors and warnings object? (I mean a public
> > function for it)
> >
> I see. I think you could try to write it with the internal functions
> that I mention in the rest of this message and then we can more easily
> see which parts are currently "internal" that could be "external":
>
> 1) Most important you need an easy way to get the the "diagnostic"
> object at point. This is held by the overlays within their
> 'flymake--diagnostic' property.
>
> 2) You'll probably need accessors for the flymake--diag object (text,
> type, issuing backend function). I think this is a question of renameing
> the existing flymake--diag-text, flymake--diag-type,
> flymake--diag-backend.
>
> 3) Perhaps a way to get all the diagnostics in a region. There is
> flymake--overlays for this.
>
> 4) Maybe check the properties (severity) of a given type? This is
> currently done via flymake--lookup-type-property.
>
> My only doubt is if 1 and 3 should work through the overlays API
> (flymake--overlays and overlay-get for discrimination) i.e. If so the
> API is smaller, but ties Flymake to an overlay overlay-based
> implementation. Otherwise we can make flymake-diagnostics-at-point
> etc...
>
> > because I don't feel the fear of devel's change.
>
> :-)
>
> João
>

[-- Attachment #2: Type: text/html, Size: 4798 bytes --]

Re: feature request: public API to get new flymake's errors/warnings

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 1039 bytes --]

Yuta Yamada <sleepboy.zzz@gmail.com> writes:

> --- code:
> (defun flymake-tip-get-diag-text-on-line ()
>     "Return list of string of error/warning info on the current line."
>     (cl-loop for ov in (flymake--overlays :beg (point-at-bol) :end (point-at-eol))
>              collect (flymake--diag-text (overlay-get ov 'flymake--diagnostic))))
> ---
>
> As you can see, I used 1 (flymake--overlays), 2 (flymake--diag-text), 3 (flymake--diagnostic).
> So, I hope those functions/symbol become public API. (i mean "-"
> instead of "--")

Thanks,

The attached patch augments the API for these purposes (and describes it
in the manual).

You should be able to just do:

  (defun flymake-tip-get-diag-text-on-line ()
      "Return list of string of error/warning info on the current line."
      (cl-loop for diag in (flymake-diagnostics (point-at-bol) (point-at-eol))
               collect (flymake-diagnostic-text diag)))

If noone objects I shall push the patch to emacs-26 in a couple of days time.

João


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Augment-Flymake-API-for-third-party-extensions.patch --]
[-- Type: text/x-diff, Size: 10673 bytes --]

From 46366c45cb1cef5c0cc88bb9a868df88f4ed5c1a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= <joaotavora@gmail.com>
Date: Thu, 19 Oct 2017 12:33:20 +0100
Subject: [PATCH] Augment Flymake API for third-party extensions

See
https://lists.gnu.org/archive/html/emacs-devel/2017-10/msg00619.html

* doc/misc/flymake.texi (Flymake error types): Rewrite
example.
(Flymake utility functions): Augment with new API.

* lisp/progmodes/flymake.el (flymake-diagnostics): New function.
(flymake--diag-accessor): New helper macro.
(flymake-diagnostic-buffer, flymake-diagnostic-text)
(flymake-diagnostic-beg, flymake-diagnostic-end)
(flymake-diagnostic-backend): Accessors for diagnostic objects.
(flymake--overlays): Use flymake-diagnostic property.
(flymake--highlight-line): Simplify.  Only set
flymake-diagnostic property.
(flymake--handle-report, flymake-goto-next-error): Use
flymake-diagnostic property.
(flymake-show-diagnostic): Use diagnostic object.
(flymake--diagnostics-buffer-entries): Use
flymake-diagnostics.
---
 doc/misc/flymake.texi     | 61 +++++++++++++++++++++++++++++++----------------
 lisp/progmodes/flymake.el | 56 ++++++++++++++++++++++++++++---------------
 2 files changed, 78 insertions(+), 39 deletions(-)

diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 99ab1271ac..6e0928f0ee 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -361,34 +361,38 @@ Flymake error types
                          (flymake-category . flymake-note))))
 @end example
 
-@vindex flymake-text
+@vindex flymake-diagnostics
+@vindex flymake-diagnostic-backend
+@vindex flymake-diagnostic-buffer
+@vindex flymake-diagnostic-text
+@vindex flymake-diagnostic-beg
+@vindex flymake-diagnostic-end
 As you might have guessed, Flymake's annotations are implemented as
 overlays (@pxref{Overlays,,, elisp, The Emacs Lisp Reference Manual}).
 Along with the properties that you specify for the specific type of
-diagnostic, Flymake adds the property @code{flymake-text} to these
-overlays, and sets it to the message string that the backend used to
-describe the diagnostic.
+diagnostic, Flymake adds the property @code{flymake-diagnostic} to
+these overlays, and sets it to the object that the backend created
+with @code{flymake-make-diagnostic}.
 
-Since overlays also support arbitrary keymaps, you can use this
-property @code{flymake-text} to create interactive annotations, such
-as in the following example of binding a @kbd{mouse-3} event (middle
-mouse button click) to an Internet search for the text of a
-@code{:warning} or @code{:error}.
+Since overlays also support arbitrary keymaps, you can this along with
+the functions @code{flymake-diagnostics} and
+@code{flymake-diagnostic-text} (@pxref{Flymake utility functions}) to
+create interactive annotations, such as in the following example of
+binding a @kbd{mouse-3} event (middle mouse button click) to an
+Internet search for the text of a @code{:warning} or @code{:error}.
 
 @example
 (defun my-search-for-message (event)
   (interactive "e")
-  (let ((ovs (overlays-at (posn-point (event-start event))))
-        ov)
-    ;; loop until flymake overlay we clicked on is recovered
-    (while (not (overlay-get (setq ov (pop ovs)) 'flymake-text)))
-    (when ov
-      (eww-browse-url
-       (concat "https://duckduckgo.com/?q="
-               (replace-regexp-in-string " "
-                                         "+"
-                                         (overlay-get ov 'flymake-text)))
-       t))))
+  (let* ((diags (flymake-diagnostics (posn-point (event-start event))))
+         (topmost-diag (car diags)))
+    (eww-browse-url
+       (concat
+        "https://duckduckgo.com/?q="
+        (replace-regexp-in-string " "
+                                  "+"
+                                  (flymake-diagnostic-text topmost-diag)))
+       t)))
 
 (dolist (type '(:warning :error))
   (let ((a (assoc type flymake-diagnostic-types-alist)))
@@ -513,6 +517,23 @@ Flymake utility functions
 of the problem detected in this region.
 @end deffn
 
+@cindex access diagnostic object
+These objects' properties can be accessed with the functions
+@code{flymake-diagnostic-backend}, @code{flymake-diagnostic-buffer},
+@code{flymake-diagnostic-text}, @code{flymake-diagnostic-beg},
+@code{flymake-diagnostic-end} and @code{flymake-diagnostic-type}.
+
+Additionally, the function @code{flymake-diagnostics} will collect
+such objects in the region you specify.
+
+@cindex collect diagnostic objects
+@deffn Function flymake-diagnostics beg end
+Get a list of Flymake diagnostics in the region comprised between
+@var{beg} and @var{end}.  If neither @var{beg} or @var{end} is
+supplied, use the whole buffer, otherwise if @var{beg} is non-nil and
+@var{end} is nil, consider only diagnostics at @var{beg}.
+@end deffn
+
 @cindex buffer position from line and column number
 It is often the case with external syntax tools that a diagnostic's
 position is reported in terms of a line number, and sometimes a column
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index 5d5f9bb75d..fc5e3b80ef 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -228,6 +228,29 @@ flymake-make-diagnostic
 description of the problem detected in this region."
   (flymake--diag-make :buffer buffer :beg beg :end end :type type :text text))
 
+;;;###autoload
+(defun flymake-diagnostics (&optional beg end)
+  "Get Flymake diagnostics in region comprised between BEG and END.
+
+If neither BEG or END is supplied, use the whole buffer,
+otherwise if BEG is non-nil and END is nil, consider only
+diagnostics at BEG."
+  (mapcar (lambda (ov) (overlay-get ov 'flymake-diagnostic))
+          (flymake--overlays :beg beg :end end)))
+
+(defmacro flymake--diag-accessor (public internal thing)
+  "Make PUBLIC an alias for INTERNAL, add doc using THING."
+  `(defsubst ,public (diag)
+     ,(format "Get Flymake diagnostic DIAG's %s." (symbol-name thing))
+     (,internal diag)))
+
+(flymake--diag-accessor flymake-diagnostic-buffer flymake--diag-buffer buffer)
+(flymake--diag-accessor flymake-diagnostic-text flymake--diag-text text)
+(flymake--diag-accessor flymake-diagnostic-type flymake--diag-type type)
+(flymake--diag-accessor flymake-diagnostic-beg flymake--diag-beg beg)
+(flymake--diag-accessor flymake-diagnostic-end flymake--diag-end end)
+(flymake--diag-accessor flymake-diagnostic-backend flymake--diag-backend backend)
+
 (cl-defun flymake--overlays (&key beg end filter compare key)
   "Get flymake-related overlays.
 If BEG is non-nil and END is nil, consider only `overlays-at'
@@ -238,7 +261,7 @@ flymake-make-diagnostic
     (widen)
     (let ((ovs (cl-remove-if-not
                 (lambda (ov)
-                  (and (overlay-get ov 'flymake)
+                  (and (overlay-get ov 'flymake-diagnostic)
                        (or (not filter)
                            (funcall filter ov))))
                 (if (and beg (null end))
@@ -498,18 +521,15 @@ flymake--highlight-line
       (default-maybe 'help-echo
         (lambda (_window _ov pos)
           (mapconcat
-           (lambda (ov)
-             (overlay-get ov 'flymake-text))
-           (flymake--overlays :beg pos)
+           #'flymake--diag-text
+           (flymake-diagnostics pos)
            "\n")))
       (default-maybe 'severity (warning-numeric-level :error))
       (default-maybe 'priority (+ 100 (overlay-get ov 'severity))))
     ;; Some properties can't be overridden.
     ;;
     (overlay-put ov 'evaporate t)
-    (overlay-put ov 'flymake t)
-    (overlay-put ov 'flymake-text (flymake--diag-text diagnostic))
-    (overlay-put ov 'flymake--diagnostic diagnostic)))
+    (overlay-put ov 'flymake-diagnostic diagnostic)))
 
 ;; Nothing in Flymake uses this at all any more, so this is just for
 ;; third-party compatibility.
@@ -600,7 +620,7 @@ flymake-is-running
              (lambda (ov)
                (eq backend
                    (flymake--diag-backend
-                    (overlay-get ov 'flymake--diagnostic))))))
+                    (overlay-get ov 'flymake-diagnostic))))))
           (mapc (lambda (diag)
                   (flymake--highlight-line diag)
                   (setf (flymake--diag-backend diag) backend))
@@ -899,7 +919,7 @@ flymake-goto-next-error
                                  (lambda (ov)
                                    (let ((diag (overlay-get
                                                 ov
-                                                'flymake--diagnostic)))
+                                                'flymake-diagnostic)))
                                      (and diag
                                           (or (not filter)
                                               (memq (flymake--diag-type diag)
@@ -1089,13 +1109,13 @@ flymake-show-diagnostic
   (interactive (list (point) t))
   (let* ((id (or (tabulated-list-get-id pos)
                  (user-error "Nothing at point")))
-         (overlay (plist-get id :overlay)))
-    (with-current-buffer (overlay-buffer overlay)
+         (diag (plist-get id :diagnostic)))
+    (with-current-buffer (flymake--diag-buffer diag)
       (with-selected-window
           (display-buffer (current-buffer) other-window)
-        (goto-char (overlay-start overlay))
-        (pulse-momentary-highlight-region (overlay-start overlay)
-                                          (overlay-end overlay)
+        (goto-char (flymake--diag-beg diag))
+        (pulse-momentary-highlight-region (flymake--diag-beg diag)
+                                          (flymake--diag-end diag)
                                           'highlight))
       (current-buffer))))
 
@@ -1108,18 +1128,16 @@ flymake-goto-diagnostic
 
 (defun flymake--diagnostics-buffer-entries ()
   (with-current-buffer flymake--diagnostics-buffer-source
-    (cl-loop for ov in (flymake--overlays)
-             for diag = (overlay-get ov
-                                     'flymake--diagnostic)
+    (cl-loop for diag in (flymake-diagnostics)
              for (line . col) =
              (save-excursion
-               (goto-char (overlay-start ov))
+               (goto-char (flymake--diag-beg diag))
                (cons (line-number-at-pos)
                      (- (point)
                         (line-beginning-position))))
              for type = (flymake--diag-type diag)
              collect
-             (list (list :overlay ov
+             (list (list :diagnostic diag
                          :line line
                          :severity (flymake--lookup-type-property
                                     type
-- 
2.14.2

Re: feature request: public API to get new flymake's errors/warnings

[Yuta Yamada]

[-- Attachment #1: Type: text/plain, Size: 1709 bytes --]

>
> You should be able to just do:
>
>   (defun flymake-tip-get-diag-text-on-line ()
>       "Return list of string of error/warning info on the current line."
>       (cl-loop for diag in (flymake-diagnostics (point-at-bol)
> (point-at-eol))
>                collect (flymake-diagnostic-text diag)))
>
> If noone objects I shall push the patch to emacs-26 in a couple of days
> time.
>

Thanks Joao, there is no objection from me.
I'll try `flymake-diagnostic-XXX' stuff after you pushed.

Yuta Yamada

On Thu, Oct 19, 2017 at 4:36 AM, João Távora <joaotavora@gmail.com> wrote:

> Yuta Yamada <sleepboy.zzz@gmail.com> writes:
>
> > --- code:
> > (defun flymake-tip-get-diag-text-on-line ()
> >     "Return list of string of error/warning info on the current line."
> >     (cl-loop for ov in (flymake--overlays :beg (point-at-bol) :end
> (point-at-eol))
> >              collect (flymake--diag-text (overlay-get ov
> 'flymake--diagnostic))))
> > ---
> >
> > As you can see, I used 1 (flymake--overlays), 2 (flymake--diag-text), 3
> (flymake--diagnostic).
> > So, I hope those functions/symbol become public API. (i mean "-"
> > instead of "--")
>
> Thanks,
>
> The attached patch augments the API for these purposes (and describes it
> in the manual).
>
> You should be able to just do:
>
>   (defun flymake-tip-get-diag-text-on-line ()
>       "Return list of string of error/warning info on the current line."
>       (cl-loop for diag in (flymake-diagnostics (point-at-bol)
> (point-at-eol))
>                collect (flymake-diagnostic-text diag)))
>
> If noone objects I shall push the patch to emacs-26 in a couple of days
> time.
>
> João
>
>

[-- Attachment #2: Type: text/html, Size: 2580 bytes --]

Re: feature request: public API to get new flymake's errors/warnings

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Date: Thu, 19 Oct 2017 12:36:05 +0100
> Cc: emacs-devel@gnu.org
> 
> The attached patch augments the API for these purposes (and describes it
> in the manual).

A few comments to the documentation:

> -Since overlays also support arbitrary keymaps, you can use this
> -property @code{flymake-text} to create interactive annotations, such
> -as in the following example of binding a @kbd{mouse-3} event (middle
> -mouse button click) to an Internet search for the text of a
> -@code{:warning} or @code{:error}.
> +Since overlays also support arbitrary keymaps, you can this along with
                                                  ^^^^^^^^^^^^
The "use" part is missing.

> +the functions @code{flymake-diagnostics} and
> +@code{flymake-diagnostic-text} (@pxref{Flymake utility functions}) to
> +create interactive annotations, such as in the following example of
> +binding a @kbd{mouse-3} event (middle mouse button click) to an
             ^^^^^^^^^^^^^
Since you are talking about an event, not something that the user
does, @code is a better markup here.

> +@deffn Function flymake-diagnostics beg end
> +Get a list of Flymake diagnostics in the region comprised between
> +@var{beg} and @var{end}.  If neither @var{beg} or @var{end} is

I'd say "in the region determined by @var{beg} and @var{end}".  I
think it's both more correct English and avoids misinterpretation of
what exactly "between" means (is in exclusive or inclusive?).

> +supplied, use the whole buffer, otherwise if @var{beg} is non-nil and
> +@var{end} is nil, consider only diagnostics at @var{beg}.

"nil" should have the @code markup (2 counts).

> +(defun flymake-diagnostics (&optional beg end)
> +  "Get Flymake diagnostics in region comprised between BEG and END.

Same comment here about the "comprised between" part.

Thanks.

Re: feature request: public API to get new flymake's errors/warnings

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> The attached patch augments the API for these purposes (and describes it
>> in the manual).
>
> A few comments to the documentation:

Thanks. All fixed, and pushed.

João

Re: feature request: public API to get new flymake's errors/warnings

[Stefan Monnier]

>> +Since overlays also support arbitrary keymaps, you can this along with
>                                                   ^^^^^^^^^^^^
> The "use" part is missing.

Maybe we should just lobby for the new verb "to this", as in "boy, he
really thissed it hard!"

>> +(defun flymake-diagnostics (&optional beg end)
>> +  "Get Flymake diagnostics in region comprised between BEG and END.
> Same comment here about the "comprised between" part.

I don't have an opinion on what's the best phrasing for that in the
Texinfo doc, but in the docstrings, we traditionally just say

    Get flymake diagnostics in region BEG..END


-- Stefan

Re: feature request: public API to get new flymake's errors/warnings

[Yuri Khan]

On Fri, Oct 20, 2017 at 7:47 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:
>>> +Since overlays also support arbitrary keymaps, you can this along with
>>                                                  ^^^^^^^^^^^^
>> The "use" part is missing.
>
> Maybe we should just lobby for the new verb "to this", as in "boy, he
> really thissed it hard!"

Hey, if it’s a verb, it’s probably an irregular one. Maybe this/thus/thus.

Re: feature request: public API to get new flymake's errors/warnings

[João Távora]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> +Since overlays also support arbitrary keymaps, you can this along with
>>                                                   ^^^^^^^^^^^^
>> The "use" part is missing.
>
> Maybe we should just lobby for the new verb "to this", as in "boy, he
> really thissed it hard!"

I admit to being easily thistracted...

> Texinfo doc, but in the docstrings, we traditionally just say
>
>     Get flymake diagnostics in region BEG..END

If it helps, BEG non-nil and END nil are a special case here, so maybe
that justifies the non-standard "determined by BEG and END"
phrasing. Feel free to change though.

João