all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Lisp Api and backward compatibility
@ 2019-04-12 20:09 Sameer Rahmani
  2019-04-12 20:20 ` Eli Zaretskii
  2019-04-14  1:18 ` Richard Stallman
  0 siblings, 2 replies; 6+ messages in thread
From: Sameer Rahmani @ 2019-04-12 20:09 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Lisp Api and backward compatibility
  2019-04-12 20:09 Lisp Api and backward compatibility Sameer Rahmani
@ 2019-04-12 20:20 ` Eli Zaretskii
  2019-04-12 20:28   ` Sameer Rahmani
  2019-04-14  1:18 ` Richard Stallman
  1 sibling, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2019-04-12 20:20 UTC (permalink / raw)
  To: Sameer Rahmani; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Lisp Api and backward compatibility
  2019-04-12 20:20 ` Eli Zaretskii
@ 2019-04-12 20:28   ` Sameer Rahmani
  2019-04-12 20:38     ` Eli Zaretskii
  2019-04-12 21:13     ` Drew Adams
  0 siblings, 2 replies; 6+ messages in thread
From: Sameer Rahmani @ 2019-04-12 20:28 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

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 ?





^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Lisp Api and backward compatibility
  2019-04-12 20:28   ` Sameer Rahmani
@ 2019-04-12 20:38     ` Eli Zaretskii
  2019-04-12 21:13     ` Drew Adams
  1 sibling, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2019-04-12 20:38 UTC (permalink / raw)
  To: Sameer Rahmani; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* RE: Lisp Api and backward compatibility
  2019-04-12 20:28   ` Sameer Rahmani
  2019-04-12 20:38     ` Eli Zaretskii
@ 2019-04-12 21:13     ` Drew Adams
  1 sibling, 0 replies; 6+ messages in thread
From: Drew Adams @ 2019-04-12 21:13 UTC (permalink / raw)
  To: Sameer Rahmani, Eli Zaretskii; +Cc: emacs-devel

> 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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Lisp Api and backward compatibility
  2019-04-12 20:09 Lisp Api and backward compatibility Sameer Rahmani
  2019-04-12 20:20 ` Eli Zaretskii
@ 2019-04-14  1:18 ` Richard Stallman
  1 sibling, 0 replies; 6+ messages in thread
From: Richard Stallman @ 2019-04-14  1:18 UTC (permalink / raw)
  To: Sameer Rahmani; +Cc: emacs-devel

[[[ 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)





^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2019-04-14  1:18 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-04-12 20:09 Lisp Api and backward compatibility Sameer Rahmani
2019-04-12 20:20 ` Eli Zaretskii
2019-04-12 20:28   ` Sameer Rahmani
2019-04-12 20:38     ` Eli Zaretskii
2019-04-12 21:13     ` Drew Adams
2019-04-14  1:18 ` Richard Stallman

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.