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

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Richard Copley-2
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.)



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Richard Copley <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Richard Copley-2


On Wed, 15 May 2019 at 07:04, Lars Ingebrigtsen <[hidden email]> wrote:
Richard Copley <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Richard Copley <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
In reply to this post by Richard Copley-2
Richard Copley <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
In reply to this post by Richard Copley-2
Richard Copley <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
In reply to this post by 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




Reply | Threaded
Open this post in threaded view
|

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

Richard Copley-2

On Wed, 15 May 2019 at 08:46, Lars Ingebrigtsen <[hidden email]> 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))

Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Richard Copley <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Richard Copley-2


On Thu, 16 May 2019 at 04:59, Lars Ingebrigtsen <[hidden email]> wrote:
Richard Copley <[hidden email]> 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.