GNU bug report logs - #24694
Document url--allow-chars for external use?

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24694 in the body.
You can then email your comments to 24694 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: Document url--allow-chars for external use?
Date: Fri, 14 Oct 2016 11:24:52 -0700

[Message part 1 (text/plain, inline)]

Currently url-hexify-string has an optional argument allowed-chars,
which is a long vector. However, it is more natural to specify a list of
characters. Internally, the default value of allowed-chars is specified
by converting a list of chars to such a vector by using an internal
function url--allow-chars. I would like to suggest to document
url--allow-chars for external use, thus we can improve the interface of
the url-hexify-string function.

I can draft the document change, if you agree with me.

[signature.asc (application/pgp-signature, attachment)]

Message #8 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 14 Oct 2016 22:02:24 +0300

> From: Hong Xu <hong <at> topbug.net>
> Date: Fri, 14 Oct 2016 11:24:52 -0700
> 
> Currently url-hexify-string has an optional argument allowed-chars,
> which is a long vector. However, it is more natural to specify a list of
> characters. Internally, the default value of allowed-chars is specified
> by converting a list of chars to such a vector by using an internal
> function url--allow-chars. I would like to suggest to document
> url--allow-chars for external use, thus we can improve the interface of
> the url-hexify-string function.
> 
> I can draft the document change, if you agree with me.

Isn't it better to teach url-hexify-string to accept lists as well?

Message #11 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 14 Oct 2016 12:36:04 -0700

[Message part 1 (text/plain, inline)]

On 10/14/2016 12:02 PM, Eli Zaretskii wrote:
>> From: Hong Xu <hong <at> topbug.net>
>> Date: Fri, 14 Oct 2016 11:24:52 -0700
>>
>> Currently url-hexify-string has an optional argument allowed-chars,
>> which is a long vector. However, it is more natural to specify a list of
>> characters. Internally, the default value of allowed-chars is specified
>> by converting a list of chars to such a vector by using an internal
>> function url--allow-chars. I would like to suggest to document
>> url--allow-chars for external use, thus we can improve the interface of
>> the url-hexify-string function.
>>
>> I can draft the document change, if you agree with me.
> 
> Isn't it better to teach url-hexify-string to accept lists as well?
> 
Yes, that would be even better.

[signature.asc (application/pgp-signature, attachment)]

Message #14 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Thu, 01 Dec 2016 13:28:17 -0800

[Message part 1 (text/plain, inline)]

On 2016-10-14 Fri 12:02 GMT-0800, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Hong Xu <hong <at> topbug.net>
>> Date: Fri, 14 Oct 2016 11:24:52 -0700
>> 
>> Currently url-hexify-string has an optional argument allowed-chars,
>> which is a long vector. However, it is more natural to specify a list of
>> characters. Internally, the default value of allowed-chars is specified
>> by converting a list of chars to such a vector by using an internal
>> function url--allow-chars. I would like to suggest to document
>> url--allow-chars for external use, thus we can improve the interface of
>> the url-hexify-string function.
>> 
>> I can draft the document change, if you agree with me.
>
> Isn't it better to teach url-hexify-string to accept lists as well?

The patch is attached.

Make url-hexify-string accept a list of allowed chars.

	* url-util.el (url-hexify-string): Accept a list of allowed chars.
	* url.texi (URI Encoding): Update url-hexify-string doc and index improvements.

[url.patch (text/x-diff, inline)]

diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index 91cb6b54a847..b5e6e2ce465a 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -221,6 +221,7 @@ URI Encoding
 @section URI Encoding
 
 @cindex percent encoding
+@findex url-generic-parse-url
   The @code{url-generic-parse-url} parser does not obey RFC 3986 in
 one respect: it allows non-@acronym{ASCII} characters in URI strings.
 
@@ -233,6 +234,7 @@ URI Encoding
 @acronym{ASCII} characters must also be percent encoded when they
 appear in URI components.)
 
+@findex url-encode-url
   The function @code{url-encode-url} can be used to convert a URI
 string containing arbitrary characters to one that is properly
 percent-encoded in accordance with RFC 3986.
@@ -244,11 +246,13 @@ URI Encoding
 previously uppercase.
 @end defun
 
+@findex url-hexify-string
+@findex url-unhex-string
   To convert between a string containing arbitrary characters and a
 percent-encoded all-@acronym{ASCII} string, use the functions
 @code{url-hexify-string} and @code{url-unhex-string}:
 
-@defun url-hexify-string string &optional allowed-chars
+@defun url-hexify-string string &optional allowed-chars list-chars
 This function performs percent-encoding on @var{string}, and returns
 the result.
 
diff --git a/lisp/url/url-util.el b/lisp/url/url-util.el
index 1ae2213eee65..96fc741a1700 100644
--- a/lisp/url/url-util.el
+++ b/lisp/url/url-util.el
@@ -398,18 +398,23 @@ url--allowed-chars
     vec))
 
 ;;;###autoload
-(defun url-hexify-string (string &optional allowed-chars)
+(defun url-hexify-string (string &optional allowed-chars list-chars)
   "URI-encode STRING and return the result.
 If STRING is multibyte, it is first converted to a utf-8 byte
 string.  Each byte corresponding to an allowed character is left
 as-is, while all other bytes are converted to a three-character
 string: \"%\" followed by two upper-case hex digits.
 
-The allowed characters are specified by ALLOWED-CHARS.  If this
+The allowed characters are specified by ALLOWED-CHARS. If this
 argument is nil, the list `url-unreserved-chars' determines the
-allowed characters.  Otherwise, ALLOWED-CHARS should be a vector
-whose Nth element is non-nil if character N is allowed."
-  (unless allowed-chars
+allowed characters.  Otherwise, if LIST-CHARS is nil or omitted,
+ALLOWED-CHARS should be a vector whose Nth element is non-nil if
+character N is allowed; if LIST-CHARS is non-nil, ALLOWED-CHARS
+should be a list of allowed chars.
+"
+  (if allowed-chars
+      (when list-chars
+        (setq allowed-chars (url--allowed-chars allowed-chars)))
     (setq allowed-chars (url--allowed-chars url-unreserved-chars)))
   (mapconcat (lambda (byte)
 	       (if (aref allowed-chars byte)

[signature.asc (application/pgp-signature, inline)]

Message #19 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 4 Oct 2019 12:31:27 -0700

On 12/1/16 1:28 PM, Hong Xu wrote:
> 
> On 2016-10-14 Fri 12:02 GMT-0800, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>>> From: Hong Xu <hong <at> topbug.net>
>>> Date: Fri, 14 Oct 2016 11:24:52 -0700
>>>
>>> Currently url-hexify-string has an optional argument allowed-chars,
>>> which is a long vector. However, it is more natural to specify a list of
>>> characters. Internally, the default value of allowed-chars is specified
>>> by converting a list of chars to such a vector by using an internal
>>> function url--allow-chars. I would like to suggest to document
>>> url--allow-chars for external use, thus we can improve the interface of
>>> the url-hexify-string function.
>>>
>>> I can draft the document change, if you agree with me.
>>
>> Isn't it better to teach url-hexify-string to accept lists as well?
> 
> The patch is attached.
> 
> Make url-hexify-string accept a list of allowed chars.
> 
> 	* url-util.el (url-hexify-string): Accept a list of allowed chars.
> 	* url.texi (URI Encoding): Update url-hexify-string doc and index improvements.
> 

It's been a few years... I'm wondering whether this patch is still interesting?

Message #22 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 11 Oct 2019 15:38:03 +0300

> From: Hong Xu <hong <at> topbug.net>
> Cc: 24694 <at> debbugs.gnu.org
> Date: Fri, 4 Oct 2019 12:31:27 -0700
> 
> > Make url-hexify-string accept a list of allowed chars.
> > 
> > 	* url-util.el (url-hexify-string): Accept a list of allowed chars.
> > 	* url.texi (URI Encoding): Update url-hexify-string doc and index improvements.
> > 
> 
> It's been a few years... I'm wondering whether this patch is still interesting?

I think it is, yes.  Can you send a patch relative to the current
master branch?

Thanks.

Message #25 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org, Hong Xu <hong <at> topbug.net>
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 11 Oct 2019 16:32:35 +0200

>>>>> On Fri, 11 Oct 2019 15:38:03 +0300, Eli Zaretskii <eliz <at> gnu.org> said:

    >> From: Hong Xu <hong <at> topbug.net>
    >> Cc: 24694 <at> debbugs.gnu.org
    >> Date: Fri, 4 Oct 2019 12:31:27 -0700
    >> 
    >> > Make url-hexify-string accept a list of allowed chars.
    >> > 
    >> > 	* url-util.el (url-hexify-string): Accept a list of allowed chars.
    >> > 	* url.texi (URI Encoding): Update url-hexify-string doc and index improvements.
    >> > 
    >> 
    >> It's been a few years... I'm wondering whether this patch is still interesting?

    Eli> I think it is, yes.  Can you send a patch relative to the current
    Eli> master branch?

Api nit: if the first argument is going to be a list or a vector, you
could just keep one argument and check 'vectorp'.

Robert

Message #28 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Robert Pluim <rpluim <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Fri, 11 Oct 2019 19:21:34 -0700

[Message part 1 (text/plain, inline)]

On 10/11/19 7:32 AM, Robert Pluim wrote:
>>>>>> On Fri, 11 Oct 2019 15:38:03 +0300, Eli Zaretskii <eliz <at> gnu.org> said:
> 
>      >> From: Hong Xu <hong <at> topbug.net>
>      >> Cc: 24694 <at> debbugs.gnu.org
>      >> Date: Fri, 4 Oct 2019 12:31:27 -0700
>      >>
>      >> > Make url-hexify-string accept a list of allowed chars.
>      >> >
>      >> > 	* url-util.el (url-hexify-string): Accept a list of allowed chars.
>      >> > 	* url.texi (URI Encoding): Update url-hexify-string doc and index improvements.
>      >> >
>      >>
>      >> It's been a few years... I'm wondering whether this patch is still interesting?
> 
>      Eli> I think it is, yes.  Can you send a patch relative to the current
>      Eli> master branch?
> 
> Api nit: if the first argument is going to be a list or a vector, you
> could just keep one argument and check 'vectorp'.
> 

Thanks, I've updated the patch as attached.

[0001-Make-url-hexify-string-accept-a-list-of-allowed-char.patch (text/x-patch, attachment)]

Message #31 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 24694 <at> debbugs.gnu.org, rpluim <at> gmail.com
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Sat, 12 Oct 2019 12:11:47 +0300

> Cc: 24694 <at> debbugs.gnu.org
> From: Hong Xu <hong <at> topbug.net>
> Date: Fri, 11 Oct 2019 19:21:34 -0700
> 
> Thanks, I've updated the patch as attached.

I have a couple of minor comments:

> * url-util.el (url-hexify-string): Accept a list of allowed chars.
> * url.texi (URI Encoding): Update url-hexify-string doc and index
> improvements.

The log message should specify each file with leading directories
starting from the root of the Emacs tree.  E.g., url-util.el should be
shown as lisp/url/url-util.el.

Also, please always mention the bug number in the log message.

These and other stylistic issues are described in detail in
CONTRIBUTE.

> +allowed characters.  Otherwise, ALLOWED-CHARS should be either a
> +vector whose Nth element is non-nil if character N is allowed or
> +a list of allowed chars.                                     ^

Please insert a comma where indicated, it will make the sentence
easier to read.

Thanks.

Message #34 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24694 <at> debbugs.gnu.org, rpluim <at> gmail.com
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Sat, 12 Oct 2019 11:23:48 -0700

[Message part 1 (text/plain, inline)]

On 10/12/19 2:11 AM, Eli Zaretskii wrote:
> 
> I have a couple of minor comments:

I've attached an update.


> 
> The log message should specify each file with leading directories
> starting from the root of the Emacs tree.  E.g., url-util.el should be
> shown as lisp/url/url-util.el.

Done.

> 
> Also, please always mention the bug number in the log message.

Done.

> 
>> +allowed characters.  Otherwise, ALLOWED-CHARS should be either a
>> +vector whose Nth element is non-nil if character N is allowed or
>> +a list of allowed chars.                                     ^
> 
> Please insert a comma where indicated, it will make the sentence
> easier to read.

I swapped the two choices (the shorter one goes first) and hopefully this will be easier to read. Also updated the doc in url.texi.

[0001-Make-url-hexify-string-accept-a-list-of-allowed-char.patch (text/x-patch, attachment)]

Message #37 received at 24694 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 24694 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, rpluim <at> gmail.com
Subject: Re: bug#24694: Document url--allow-chars for external use?
Date: Mon, 14 Oct 2019 06:47:12 +0200

Hong Xu <hong <at> topbug.net> writes:

>> I have a couple of minor comments:
>
> I've attached an update.

Thanks; applied to the trunk now.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.