bug#25735: 26.0.50; url-retrieve errors are peculiar

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Richard Copley]

Within the docstring for url-retrieve, it says: "[...] The
error can be signaled with (signal ERROR-SYMBOL DATA) [...]",
but in current master (grep for ":error" in "lisp/url/*.el") the actual
usage is that ERROR-SYMBOL is `error' and DATA is a list that starts
with a symbol, for example (connection-failed "failed with code 10061"
:host "localhost" :service 80). The docstring hints at something
like this:

  (url-retrieve (format "http://localhost/non-existent-resource")
                (lambda (status &rest args)
                  (let ((error-info (plist-get status :error)))
                    (when error-info
                      (signal (car error-info) (cdr error-info))))
                  ;;...
                  ))

which ends up calling this:

  (signal 'error
          '(connection-failed "failed with code 10061"
            :host "localhost"
            :service 80))

which ends up printing these two lines (including the newline
embedded in a string) to the echo area:

error in process sentinel: peculiar error: "failed with code 10061
", :host, "localhost", :service, 80

Unfortunately the error code itself, `connection-failed', is dropped.
(See print_error_message in "print.c"; if ERROR-SYMBOL is `error' then
the car of DATA, say ERRMSG, is printed if it is a string; if ERRMSG
is not a string then "peculiar error" is printed instead of ERRMSG.)

Please also consider augmenting the docstring with an example of using
the error data. It's a drag for the user to have to work that out
before they are in a position to call url-retrieve!

(There's a tiny example above, but of course it assumes
that DATA has been changed to conform to the docstring.)

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

Richard Copley <rcopley@gmail.com> writes:

> Within the docstring for url-retrieve, it says: "[...] The
> error can be signaled with (signal ERROR-SYMBOL DATA) [...]",
> but in current master (grep for ":error" in "lisp/url/*.el") the actual
> usage is that ERROR-SYMBOL is `error' and DATA is a list that starts
> with a symbol, for example (connection-failed "failed with code 10061"
> :host "localhost" :service 80). The docstring hints at something
> like this:
>
>   (url-retrieve (format "http://localhost/non-existent-resource")
>                 (lambda (status &rest args)
>                   (let ((error-info (plist-get status :error)))
>                     (when error-info
>                       (signal (car error-info) (cdr error-info))))
>                   ;;...
>                   ))

I tried finding that doc string, but it doesn't seem to exist any more?
Was that in the `url-retrieve' doc string?

---
grep --color -nH --null -e "car error-info" `find . -type f`

Grep finished with no matches found at Wed May 15 08:01:26
---


> which ends up calling this:
>
>   (signal 'error
>           '(connection-failed "failed with code 10061"
>             :host "localhost"
>             :service 80))
>
> which ends up printing these two lines (including the newline
> embedded in a string) to the echo area:
>
> error in process sentinel: peculiar error: "failed with code 10061
> ", :host, "localhost", :service, 80

Yeah, that's not the right way to call `error'...

> Unfortunately the error code itself, `connection-failed', is dropped.
> (See print_error_message in "print.c"; if ERROR-SYMBOL is `error' then
> the car of DATA, say ERRMSG, is printed if it is a string; if ERRMSG
> is not a string then "peculiar error" is printed instead of ERRMSG.)
>
> Please also consider augmenting the docstring with an example of using
> the error data. It's a drag for the user to have to work that out
> before they are in a position to call url-retrieve!

Yup.  But I don't know why that example is gone -- perhaps somebody else
remembers?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Richard Copley]

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

On Wed, 15 May 2019 at 07:04, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Richard Copley <rcopley@gmail.com> writes:
>
> > Within the docstring for url-retrieve, it says: "[...] The
> > error can be signaled with (signal ERROR-SYMBOL DATA) [...]",
> > but in current master (grep for ":error" in "lisp/url/*.el") the actual
> > usage is that ERROR-SYMBOL is `error' and DATA is a list that starts
> > with a symbol, for example (connection-failed "failed with code 10061"
> > :host "localhost" :service 80). The docstring hints at something
> > like this:
> >
> >   (url-retrieve (format "http://localhost/non-existent-resource")
> >                 (lambda (status &rest args)
> >                   (let ((error-info (plist-get status :error)))
> >                     (when error-info
> >                       (signal (car error-info) (cdr error-info))))
> >                   ;;...
> >                   ))
>
> I tried finding that doc string, but it doesn't seem to exist any more?
> Was that in the `url-retrieve' doc string?
>

No, it's the best I could come up with given the "hint":
  "The error can be signaled with (signal ERROR-SYMBOL DATA)"
in the url-retrieve docstring.


> ---
> grep --color -nH --null -e "car error-info" `find . -type f`
>
> Grep finished with no matches found at Wed May 15 08:01:26
> ---
>
>
> > which ends up calling this:
> >
> >   (signal 'error
> >           '(connection-failed "failed with code 10061"
> >             :host "localhost"
> >             :service 80))
> >
> > which ends up printing these two lines (including the newline
> > embedded in a string) to the echo area:
> >
> > error in process sentinel: peculiar error: "failed with code 10061
> > ", :host, "localhost", :service, 80
>
> Yeah, that's not the right way to call `error'...
>

Yeah.


> > Unfortunately the error code itself, `connection-failed', is dropped.
> > (See print_error_message in "print.c"; if ERROR-SYMBOL is `error' then
> > the car of DATA, say ERRMSG, is printed if it is a string; if ERRMSG
> > is not a string then "peculiar error" is printed instead of ERRMSG.)
> >
> > Please also consider augmenting the docstring with an example of using
> > the error data. It's a drag for the user to have to work that out
> > before they are in a position to call url-retrieve!
>
> Yup.  But I don't know why that example is gone -- perhaps somebody else
> remembers?
>
> --
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
>

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

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

Richard Copley <rcopley@gmail.com> writes:

> No, it's the best I could come up with given the "hint":
>   "The error can be signaled with (signal ERROR-SYMBOL DATA)"
> in the url-retrieve docstring.

Oh, I misread what you wrote.

----
(:redirect REDIRECTED-TO) - the request was redirected to this URL
(:error (ERROR-SYMBOL . DATA)) - an error occurred.  The error can be
signaled with (signal ERROR-SYMBOL DATA).
----

So, yeah, that's wrong.  It should be more like

(signal ERROR-SYMBOL (format "%S" data))

I guess?  But, as you say, that's not very useful, either.  Describing
DATA would be nicer.

Here's the actual uses in url.el:

url-http.el734:		     (nconc (list :error (list 'error 'http-redirect-limit
url-http.el865:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el920:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el1446:	      (nconc (list :error (list 'error 'connection-failed why
url-queue.el127:  (when (and (eq (car status) :error)
url-queue.el190:	   (cons (list :error (list 'error 'url-queue-timeout

As we can see, the only ERROR-SYMBOL in use is `error', which makes this
even less useful, and the DATA depends on what the real error type is...

I guess we could just describe these in the doc string instead stop
talking about `signal'?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

(Sorry for sending the previous email several times; I had some problems
with the MTA...)

I've now changed the doc string to

---

\(:redirect REDIRECTED-TO) - the request was redirected to this URL.

\(:error (error type . DATA)) - an error occurred.  TYPE is a
symbol that says something about where the error occurred, and
DATA is a list (possibly nil) that describes the error further.


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Richard Copley]

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

On Wed, 15 May 2019 at 08:46, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> (Sorry for sending the previous email several times; I had some problems
> with the MTA...)
>
> I've now changed the doc string to
>
> ---
>
> \(:redirect REDIRECTED-TO) - the request was redirected to this URL.
>
> \(:error (error type . DATA)) - an error occurred.  TYPE is a
> symbol that says something about where the error occurred, and
> DATA is a list (possibly nil) that describes the error further.


If there's a way to use that data to format an error message,
it would be good to provide an example, or a "see info node X",
if it's a common idiom.

I think usually if you're looking at a docstring it's because you
want to know how to use the function (as well as what it is for
and what exactly it does, which I think are covered in this case).

This is what I ended up with, after I reported the bug.
Sadly I didn't make a note of where if anywhere I cribbed it from.

(url-retrieve URL
              (lambda (status cbargs)
                (cl-loop for (key value) on status by 'cddr
                         do (when (eq key :error) (error "%s: %s" (car
value) (cdr value))))
                BODY))

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

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

Richard Copley <rcopley@gmail.com> writes:

> If there's a way to use that data to format an error message,
> it would be good to provide an example, or a "see info node X",
> if it's a common idiom.
>
> I think usually if you're looking at a docstring it's because you
> want to know how to use the function (as well as what it is for
> and what exactly it does, which I think are covered in this case).

Well, I think we should assume that people know what arguments `error'
takes, and the structure of the error data is now documented correctly.
So I think that should be sufficient.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Richard Copley]

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

On Thu, 16 May 2019 at 04:59, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Richard Copley <rcopley@gmail.com> writes:
>
> > If there's a way to use that data to format an error message,
> > it would be good to provide an example, or a "see info node X",
> > if it's a common idiom.
> >
> > I think usually if you're looking at a docstring it's because you
> > want to know how to use the function (as well as what it is for
> > and what exactly it does, which I think are covered in this case).
>
> Well, I think we should assume that people know what arguments `error'
> takes, and the structure of the error data is now documented correctly.
> So I think that should be sufficient.
>

OK. It's (error STRING &rest ARGS), by the way.

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

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

Richard Copley <rcopley@gmail.com> writes:

> No, it's the best I could come up with given the "hint":
>   "The error can be signaled with (signal ERROR-SYMBOL DATA)"
> in the url-retrieve docstring.

Oh, I misread what you wrote.

----
(:redirect REDIRECTED-TO) - the request was redirected to this URL
(:error (ERROR-SYMBOL . DATA)) - an error occurred.  The error can be
signaled with (signal ERROR-SYMBOL DATA).
----

So, yeah, that's wrong.  It should be more like

(signal ERROR-SYMBOL (format "%S" data))

I guess?  But, as you say, that's not very useful, either.  Describing
DATA would be nicer.

Here's the actual uses in url.el:

url-http.el 734:		     (nconc (list :error (list 'error 'http-redirect-limit
url-http.el 865:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el 920:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el 1446:	      (nconc (list :error (list 'error 'connection-failed why
url-queue.el 127:  (when (and (eq (car status) :error)
url-queue.el 190:	   (cons (list :error (list 'error 'url-queue-timeout

As we can see, the only ERROR-SYMBOL in use is `error', which makes this
even less useful, and the DATA depends on what the real error type is...

I guess we could just describe these in the doc string instead stop
talking about `signal'?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#25735: 26.0.50; url-retrieve errors are peculiar

[Lars Ingebrigtsen]

Richard Copley <rcopley@gmail.com> writes:

> No, it's the best I could come up with given the "hint":
>   "The error can be signaled with (signal ERROR-SYMBOL DATA)"
> in the url-retrieve docstring.

Oh, I misread what you wrote.

----
(:redirect REDIRECTED-TO) - the request was redirected to this URL
(:error (ERROR-SYMBOL . DATA)) - an error occurred.  The error can be
signaled with (signal ERROR-SYMBOL DATA).
----

So, yeah, that's wrong.  It should be more like

(signal ERROR-SYMBOL (format "%S" data))

I guess?  But, as you say, that's not very useful, either.  Describing
DATA would be nicer.

Here's the actual uses in url.el:

url-http.el 734:		     (nconc (list :error (list 'error 'http-redirect-limit
url-http.el 865:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el 920:	       (nconc (list :error (list 'error 'http url-http-response-status))
url-http.el 1446:	      (nconc (list :error (list 'error 'connection-failed why
url-queue.el 127:  (when (and (eq (car status) :error)
url-queue.el 190:	   (cons (list :error (list 'error 'url-queue-timeout

As we can see, the only ERROR-SYMBOL in use is `error', which makes this
even less useful, and the DATA depends on what the real error type is...

I guess we could just describe these in the doc string instead stop
talking about `signal'?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no