bug#12096: 24.1; Several documented functions in URL package are not defined

bug#12096: 24.1; Several documented functions in URL package are not defined

[Aurélien Aptel]

Hi all,

url-parse.el defines functions to parse an URL. A parsed URL (with
`url-generic-parse-url') is a simple vector whose content is documented
in (info "(url)Parsed URLs").

From the info page:
> The library functions typically operate on "parsed" versions of URLs.
> These are actually vectors of the form:
>
>      [TYPE USER PASSWORD HOST PORT FILE TARGET ATTRIBUTES FULL]
>
...
>    These attributes have accessors named `url-PART', where PART is the
> name of one of the elements above, e.g., `url-host'.  Similarly, there
> are setters of the form `url-set-PART'.

There are some exceptions which are not documented:

`url-file' is not the FILE attribute accessor. The accessor is actually
`url-filename'.

`url-full' is actually `url-fullness'.

And most importantly none of the setters are defined, as this little
snippet shows:

    (let (funlist)
      (require 'url)
      (require 'url-parse)
      (mapatoms (lambda (a)
                  (when (and (fboundp a)
                             (string-match "^url-set-" (symbol-name a)))
                    (push a funlist))))
                funlist)
    ;; => (url-set-mime-charset-string)


In GNU Emacs 24.1.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.10)
 of 2012-06-11 on bitzer.hoetzel.info
Windowing system distributor `The X.Org Foundation', version 11.0.11203000
Configured using:
 `configure '--prefix=/usr' '--sysconfdir=/etc' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--with-x-toolkit=gtk' '--with-xft'
 'CFLAGS=-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector
 --param=ssp-buffer-size=4 -D_FORTIFY_SOURCE=2'
 'LDFLAGS=-Wl,-O1,--sort-common,--as-needed,-z,relro''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: fr_FR.UTF-8
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Lisp Interaction

Minor modes in effect:
  rcirc-track-minor-mode: t
  cua-mode: t
  ido-everywhere: t
  show-paren-mode: t
  rainbow-delimiters-mode: t
  yas/global-mode: t
  yas/minor-mode: t
  global-auto-complete-mode: t
  auto-complete-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
M-x r e <backspace> C-g ( m p <backspace> a p a t o
m s SPC ( l a m b d a <up> C-g <up> <return> ( l e
t SPC ( f u n l i s t ) <down> <tab> <end> SPC ( a
) <return> <tab> ( f b o u n d p SPC a ) <return> <tab>
( <up> <backspace> ( w h e n SPC ( a n d SPC ( C-e
<return> C-k <tab> C-e s t r i n g - m a t <return>
SPC " ^ u r l - s e t " SPC ( s y u <backspace> m b
o l <down> <return> SPC a ) ) ) <return> <tab> ( p
u s h SPC a SPC f u n l i s t ) ) ) <return> <tab>
f u n <return> ) <up> C-e ) C-n C-j <up> C-SPC <C-down>
C-w <up> <up> <up> <up> <up> <up> C-SPC <C-down> C-g
<up> <up> <up> <up> <up> <up> <end> <return> <tab>
( r e q u i r e SPC ' u r l ) <return> <tab> ( r e
q u i r e SPC ' u r l - p a r s e ) <down> <down> <down>
<down> <down> C-j <up> C-SPC <home> C-SPC <left> <down>
<home> C-SPC <down> C-w <up> <up> <down> <end> <up>
<up> <C-right> <C-right> <C-right> <C-right> - C-g
<down> <down> C-j M-x r e p o e <backspace> r <tab>
<return>

Recent messages:
Fill column set to 80 (was 70)
[yas] Reloaded everything....
Loading grep...done
For information about GNU Emacs and the GNU system, type C-h C-a.
Quit [2 times]
Mark set [3 times]
Mark cleared
Mark activated
Quit

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message format-spec rfc822 mml mml-sec
mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils
mailheader sendmail rfc2047 rfc2045 ietf-drums mail-utils url url-proxy
url-privacy url-expand url-methods url-history url-cookie url-util
url-parse auth-source eieio byte-opt bytecomp byte-compile cconv
macroexp gnus-util password-cache url-vars mm-util mail-prsvr mailcap
thingatpt find-func grep compile comint regexp-opt ansi-color cus-start
cus-load rcirc ring windmove cua-base ido delsel knarf-wombat-theme
mark-multiple paren expand-region expand-region-custom
expand-region-core uniquify rainbow-delimiters yasnippet advice
advice-preload dropdown-list help-fns derived easy-mmode help-mode view
easymenu assoc cl auto-complete-config auto-complete edmacro kmacro
popup server dpaste-autoloads expand-region-autoloads gccsense-autoloads
htmlize-autoloads mark-multiple-autoloads rainbow-delimiters-autoloads
package tabulated-list time-date tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image fringe
lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer loaddefs button faces cus-face files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process dbusbind
dynamic-setting system-font-setting font-render-setting move-toolbar gtk
x-toolkit x multi-tty emacs)

bug#12096: 24.1; Several documented functions in URL package are not defined

[Bastien]

Aurélien Aptel <aurelien.aptel@gmail.com> writes:

> From the info page:
>> The library functions typically operate on "parsed" versions of URLs.
>> These are actually vectors of the form:
>>
>>      [TYPE USER PASSWORD HOST PORT FILE TARGET ATTRIBUTES FULL]
>>
> ...
>>    These attributes have accessors named `url-PART', where PART is the
>> name of one of the elements above, e.g., `url-host'.  Similarly, there
>> are setters of the form `url-set-PART'.
>
> There are some exceptions which are not documented:
>
> `url-file' is not the FILE attribute accessor. The accessor is actually
> `url-filename'.
>
> `url-full' is actually `url-fullness'.
>
> And most importantly none of the setters are defined, as this little
> snippet shows:
>
>     (let (funlist)
>       (require 'url)
>       (require 'url-parse)
>       (mapatoms (lambda (a)
>                   (when (and (fboundp a)
>                              (string-match "^url-set-" (symbol-name a)))
>                     (push a funlist))))
>                 funlist)
>     ;; => (url-set-mime-charset-string)

Can you submit a patch for this?

Thanks,

-- 
 Bastien

bug#12096: 24.1; Several documented functions in URL package are not defined

[Aurélien Aptel]

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

> Can you submit a patch for this?

Yes :)

So I've looked at the history of url-parse.el and all the url-set-xxx
were removed when the the package used CL.
Instead, to set an attribute you have to use setf.

I've updated the doc (update-doc.diff) and removed a useless
constructor in url-parse.el (url-parse-cleanup.diff).

Btw, I've made my change (and commited them) to my local copy of the
bazaar repo. I'm just sending you the diff of the changes. Is there a
better way to do this? A way to send commits, maybe?

[-- Attachment #2: update-doc.diff --]
[-- Type: application/octet-stream, Size: 2300 bytes --]

=== modified file 'doc/misc/url.texi'
--- doc/misc/url.texi	2012-02-29 08:12:51 +0000
+++ doc/misc/url.texi	2012-08-02 14:25:53 +0000
@@ -126,10 +126,10 @@
 @section Parsed URLs
 @cindex parsed URLs
 The library functions typically operate on @dfn{parsed} versions of
-URLs.  These are actually vectors of the form:
+URLs.  These are actually CL structures (vectors) of the form:
 
 @example
-[@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}]
+[cl-struct-url @var{type} @var{user} @var{password} @var{host} @var{port} @var{filename} @var{target} @var{attributes} @var{fullness} @var{use-cookies}]
 @end example
 
 @noindent where
@@ -144,16 +144,19 @@
 is the host name associated with it, or @code{nil};
 @item port
 is the port number associated with it, or @code{nil};
-@item file
+@item filename
 is the ``file'' part of it, or @code{nil}.  This doesn't necessarily
 actually refer to a file;
 @item target
 is the target part, or @code{nil};
 @item attributes
 is the attributes associated with it, or @code{nil};
-@item full
+@item fullness
 is @code{t} for a fully-specified URL, with a host part indicated by
 @samp{//} after the scheme part.
+@item use-cookies
+is @code{nil} to neither send or store cookies to the server, @code{t}
+otherwise.
 @end table
 
 @findex url-type
@@ -161,23 +164,21 @@
 @findex url-password
 @findex url-host
 @findex url-port
-@findex url-file
+@findex url-filename
 @findex url-target
 @findex url-attributes
-@findex url-full
-@findex url-set-type
-@findex url-set-user
-@findex url-set-password
-@findex url-set-host
-@findex url-set-port
-@findex url-set-file
-@findex url-set-target
-@findex url-set-attributes
-@findex url-set-full
+@findex url-fullness
 These attributes have accessors named @code{url-@var{part}}, where
 @var{part} is the name of one of the elements above, e.g.,
-@code{url-host}.  Similarly, there are setters of the form
-@code{url-set-@var{part}}.
+@code{url-host}.  These attributes can be set with the same accessors
+using @code{setf}:
+
+@example
+(setf (url-port url) 80)
+@end example
+
+If @var{port} is @var{nil}, @code{url-port} returns the default port
+of the protocol.
 
 There are functions for parsing and unparsing between the string and
 vector forms.


[-- Attachment #3: url-parse-cleanup.diff --]
[-- Type: application/octet-stream, Size: 466 bytes --]

=== modified file 'lisp/url/url-parse.el'
--- lisp/url/url-parse.el	2012-07-11 23:13:41 +0000
+++ lisp/url/url-parse.el	2012-08-02 14:05:56 +0000
@@ -30,7 +30,6 @@
 (autoload 'url-scheme-get-property "url-methods")
 
 (cl-defstruct (url
-            (:constructor nil)
             (:constructor url-parse-make-urlobj
                           (&optional type user password host portspec filename
                                      target attributes fullness))

bug#12096: 24.1; Several documented functions in URL package are not defined

[Stefan Monnier]

> I've updated the doc (update-doc.diff) and removed a useless
> constructor in url-parse.el (url-parse-cleanup.diff).
[...]
>  (cl-defstruct (url
> -            (:constructor nil)
>              (:constructor url-parse-make-urlobj
>                            (&optional type user password host portspec filename
>                                       target attributes fullness))

This does not remove a useless constructor, but instead adds a useless
contructor (the ":constructor nil" thingy is there to disable the
automatic creation of a default constructor).


        Stefan

bug#12096: 24.1; Several documented functions in URL package are not defined

[Aurélien Aptel]

On Sat, Aug 4, 2012 at 9:44 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> This does not remove a useless constructor, but instead adds a useless
> contructor (the ":constructor nil" thingy is there to disable the
> automatic creation of a default constructor).

Are you sure?

(progn
  (require 'cl)
  (fmakunbound 'make-foo)
  (fmakunbound 'cake)
  (defstruct (foo (:constructor cake)) a b c)
  (mapcar 'fboundp '(make-foo cake)))

=> (nil t)

bug#12096: 24.1; Several documented functions in URL package are not defined

[Stefan Monnier]

>> This does not remove a useless constructor, but instead adds a useless
>> contructor (the ":constructor nil" thingy is there to disable the
>> automatic creation of a default constructor).

> Are you sure?

Yes.  Try it.

> (progn
>   (require 'cl)
>   (fmakunbound 'make-foo)
>   (fmakunbound 'cake)
>   (defstruct (foo (:constructor cake)) a b c)
>   (mapcar 'fboundp '(make-foo cake)))

There's a difference between (:constructor cake) and (:constructor cake
(foo bar)) where the first just gives the name to use for the default
constructor, whereas the second defines an additional constructor.


        Stefan

bug#12096: 24.1; Several documented functions in URL package are not defined

[Stefan Monnier]

> I've updated the doc (update-doc.diff) and removed a useless
> constructor in url-parse.el (url-parse-cleanup.diff).

Thanks, I installed your patch to url.texi.

> Btw, I've made my change (and commited them) to my local copy of the
> bazaar repo. I'm just sending you the diff of the changes. Is there a
> better way to do this?

That's the right way to do it, merci.

>  A way to send commits, maybe?

We can give you write access.


        Stefan