[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#24694: Document url--allow-chars for external use?
From: |
Hong Xu |
Subject: |
bug#24694: Document url--allow-chars for external use? |
Date: |
Thu, 01 Dec 2016 13:28:17 -0800 |
User-agent: |
mu4e 0.9.17; emacs 25.1.90.2 |
On 2016-10-14 Fri 12:02 GMT-0800, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Hong Xu <hong@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.
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
Description: PGP signature
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- bug#24694: Document url--allow-chars for external use?,
Hong Xu <=