Lisp Api and backward compatibility

Lisp Api and backward compatibility

[Sameer Rahmani]

Hi folks,

What should i consider before changing the signature of a function which 
is part of the public api of a library ? should I add the new argument 
as the last argument ? what do we usually do for backward compatibility ?

Cheers

Sameer

Re: Lisp Api and backward compatibility

[Eli Zaretskii]

> From: Sameer Rahmani <lxsameer@gnu.org>
> Date: Fri, 12 Apr 2019 21:09:54 +0100
> 
> What should i consider before changing the signature of a function which 
> is part of the public api of a library ? should I add the new argument 
> as the last argument ? what do we usually do for backward compatibility ?

It is best not to make incompatible changes, if that's reasonably
possible.  E.g., if there is a manifest variable that controls the
behavior, it is better to introduce an additional value of that
variable than completely change the API.

If it isn't reasonable to keep backward compatibility, then some kind
of optional behavior that defaults to the previous one is the next
best choice.

For more specific responses, please tell more about the API you think
is in need of change, and why.

Thanks.

Re: Lisp Api and backward compatibility

[Sameer Rahmani]

I picked up a task to change `desktop.el` to be able to save/read 
desktops with a name ( basically writes the desktop in to a file under a 
given name and later read from it). As you already know the 
`desktop-save` fn for example gets directory name as the first argument 
following by several optional args. So I was thinking to either:

1) Add a new optional arg called filename and ask the desktop name from 
user in interactive.

2) don't add anything to the function signature and `read-string` it in 
the function body.

what do you think ?

Re: Lisp Api and backward compatibility

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Sameer Rahmani <lxsameer@gnu.org>
> Date: Fri, 12 Apr 2019 21:28:41 +0100
> 
> I picked up a task to change `desktop.el` to be able to save/read 
> desktops with a name ( basically writes the desktop in to a file under a 
> given name and later read from it). As you already know the 
> `desktop-save` fn for example gets directory name as the first argument 
> following by several optional args. So I was thinking to either:
> 
> 1) Add a new optional arg called filename and ask the desktop name from 
> user in interactive.
> 
> 2) don't add anything to the function signature and `read-string` it in 
> the function body.

The function desktop-save is also a command, so we will need to devise
a way to let the user specify the name interactively.  And the same
for desktop-read.

I didn't think about this too much, but maybe a separate command,
called desktop-save-named, say, would be a better alternative.

RE: Lisp Api and backward compatibility

[Drew Adams]

> I picked up a task to change `desktop.el` to be able to save/read
> desktops with a name (basically writes the desktop in to a file under a
> given name and later read from it). As you already know the
> `desktop-save` fn for example gets directory name as the first argument
> following by several optional args. So I was thinking to either:
> 
> 1) Add a new optional arg called filename and ask the desktop name from
> user in interactive.
> 
> 2) don't add anything to the function signature and `read-string` it in
> the function body.
> 
> what do you think ?

Thanks for working on this.  Sorely needed, IMO.

I think you should add a separate function (a command
in fact), which accepts the name of a desktop file as
argument.  I think you should not modify `desktop-read'
to make it try to do what you want here.

In Bookmark+ I've already written function (command) 
`bmkp-desktop-read`, which  does what you want.  You can
just use it (renaming it `desktop-read-file' or whatever).
Or you can look to it for inspiration.  Or not.  The code
is derived pretty straightforwardly from `desktop-read'.

It makes use of option `bmkp-desktop-default-directory',
the default directory used when reading the desktop file
name.  You can rename that option.

It uses `bmkp--pop-to-buffer-same-window' which is just
an alias for `pop-to-buffer-same-window'.

No other changes should be needed if you want to use
`bmkp-desktop-read'.

Desktop function (command) `bmkp-desktop-change-dir'
is also defined in the same file.  It could perhaps be
useful for `desktop.el' too.  Here is the doc string:

   Change to desktop saved in DESKTOP-FILE.
   Kill the desktop as specified by variables
   ‘desktop-save-mode’ and  ‘desktop-save’.
   Clear the desktop and load DESKTOP-FILE.

The file is here:

https://www.emacswiki.org/emacs/download/bookmark%2b-1.el

Re: Lisp Api and backward compatibility

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > What should i consider before changing the signature of a function which 
  > is part of the public api of a library ? should I add the new argument 
  > as the last argument ? what do we usually do for backward compatibility ?

Would it be possible to define a new function with a different name
and leave the old function unchanged?

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)