unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Constructed docstrings for closures
@ 2015-01-16 16:18 Stefan Monnier
  2015-01-16 16:46 ` David Kastrup
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Stefan Monnier @ 2015-01-16 16:18 UTC (permalink / raw)
  To: emacs-devel

When converting backquoted lambdas to closures, I've often bumped into
the following problem:

   `(lambda (foo bar)
      ,(concat "Toto is very " blabla ".")
      (code using foo and bar (and ',blabla as well)))

So code-wise, this can be replaced by a closure just fine, but doc-wise
we don't have a way to construct a different docstring for
every closure.

I'd like to lift this restriction by offering a new feature that lets us
do something like:

   (lambda (foo bar)
     <something-magical-here>
     (code using foo and bar (and blabla as well)))

and get the closure we want with the docstring we want.

Does anyone have an idea of what the <something-magical-here>
could/should be?


        Stefan



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

* Re: Constructed docstrings for closures
  2015-01-16 16:18 Constructed docstrings for closures Stefan Monnier
@ 2015-01-16 16:46 ` David Kastrup
  2015-01-16 16:51 ` Lars Magne Ingebrigtsen
  2015-01-18 12:04 ` Ted Zlatanov
  2 siblings, 0 replies; 9+ messages in thread
From: David Kastrup @ 2015-01-16 16:46 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> When converting backquoted lambdas to closures, I've often bumped into
> the following problem:
>
>    `(lambda (foo bar)
>       ,(concat "Toto is very " blabla ".")
>       (code using foo and bar (and ',blabla as well)))
>
> So code-wise, this can be replaced by a closure just fine, but doc-wise
> we don't have a way to construct a different docstring for
> every closure.
>
> I'd like to lift this restriction by offering a new feature that lets us
> do something like:
>
>    (lambda (foo bar)
>      <something-magical-here>
>      (code using foo and bar (and blabla as well)))
>
> and get the closure we want with the docstring we want.
>
> Does anyone have an idea of what the <something-magical-here>
> could/should be?

Doing it the other way round seems much cleaner:

(with-doc-string
  (concat "Toto is very " blabla ".")
  (lambda (foo bar)
    (code using foo and bar (and blabla as well))))


-- 
David Kastrup



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

* Re: Constructed docstrings for closures
  2015-01-16 16:18 Constructed docstrings for closures Stefan Monnier
  2015-01-16 16:46 ` David Kastrup
@ 2015-01-16 16:51 ` Lars Magne Ingebrigtsen
  2015-01-16 16:52   ` Lars Magne Ingebrigtsen
  2015-01-18 12:04 ` Ted Zlatanov
  2 siblings, 1 reply; 9+ messages in thread
From: Lars Magne Ingebrigtsen @ 2015-01-16 16:51 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> I'd like to lift this restriction by offering a new feature that lets us
> do something like:
>
>    (lambda (foo bar)
>      <something-magical-here>
>      (code using foo and bar (and blabla as well)))
>
> and get the closure we want with the docstring we want.
>
> Does anyone have an idea of what the <something-magical-here>
> could/should be?

  (declare (comment (format "This is a comment about %s" bla)))

would be a natural syntax, I think?

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



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

* Re: Constructed docstrings for closures
  2015-01-16 16:51 ` Lars Magne Ingebrigtsen
@ 2015-01-16 16:52   ` Lars Magne Ingebrigtsen
  2015-01-16 20:54     ` Stefan Monnier
  0 siblings, 1 reply; 9+ messages in thread
From: Lars Magne Ingebrigtsen @ 2015-01-16 16:52 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

>   (declare (comment (format "This is a comment about %s" bla)))
>
> would be a natural syntax, I think?

I mean `documentation'.

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



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

* Re: Constructed docstrings for closures
  2015-01-16 16:52   ` Lars Magne Ingebrigtsen
@ 2015-01-16 20:54     ` Stefan Monnier
  2015-01-16 23:07       ` Artur Malabarba
  0 siblings, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2015-01-16 20:54 UTC (permalink / raw)
  To: Lars Magne Ingebrigtsen, David Kastrup; +Cc: emacs-devel

Lars suggests:
> (declare (comment (format "This is a comment about %s" bla)))
> would be a natural syntax, I think?

David prefers:
> Doing it the other way round seems much cleaner:
> (with-doc-string
>   (concat "Toto is very " blabla ".")
>   (lambda (foo bar)
>     (code using foo and bar (and blabla as well))))

There are various issues around this:
1- the code that constructs the docstring should be visible to the compiler
   (so the compiler can tell it where to find the value of the lexically
   scoped `blabla' variable).
2- it shouldn't slow down normal evaluation
3- it should be implementable without too much effort.

From that point of view I guess David's approach is promising on
the first two points, but I'm not sure what the 3rd point would
look like.

Lars's suggestion seems problematic w.r.t point #2 since `lambda' would
now have to check for a `declare'.

I considered using a special property on the docstring as well, but
that's problematic w.r.t point #1.

So please keep sending ideas.


        Stefan



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

* Re: Constructed docstrings for closures
  2015-01-16 20:54     ` Stefan Monnier
@ 2015-01-16 23:07       ` Artur Malabarba
  0 siblings, 0 replies; 9+ messages in thread
From: Artur Malabarba @ 2015-01-16 23:07 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Lars Magne Ingebrigtsen, David Kastrup, emacs-devel

> Lars suggests:
> > (declare (comment (format "This is a comment about %s" bla)))
> > would be a natural syntax, I think?
I agree this would be the most natural, but if it does slow down
evaluation (which I think it would), then it isn't worth the cost.
OTOH, it might be interesting to apply this logic to `defun's, since
they already handle `declare' forms anyway.

> David prefers:
> > Doing it the other way round seems much cleaner:
> > (with-doc-string
> >   (concat "Toto is very " blabla ".")
> >   (lambda (foo bar)
> >     (code using foo and bar (and blabla as well))))

If this is chosen, I would find the following form more natural:

(lambda-with-doc-string (foo bar)
  ;; First body form is evaluated at compile time and must return a string.
  (concat "Toto is very " blabla ".")
  ;; Everything else is a regular lambda.
  (code using foo and bar (and blabla as well)))



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

* Re: Constructed docstrings for closures
  2015-01-16 16:18 Constructed docstrings for closures Stefan Monnier
  2015-01-16 16:46 ` David Kastrup
  2015-01-16 16:51 ` Lars Magne Ingebrigtsen
@ 2015-01-18 12:04 ` Ted Zlatanov
  2015-01-18 12:19   ` David Kastrup
  2 siblings, 1 reply; 9+ messages in thread
From: Ted Zlatanov @ 2015-01-18 12:04 UTC (permalink / raw)
  To: emacs-devel

On Fri, 16 Jan 2015 11:18:26 -0500 Stefan Monnier <monnier@IRO.UMontreal.CA> wrote: 

SM> I'd like to lift this restriction by offering a new feature that lets us
SM> do something like:

SM>    (lambda (foo bar)
SM>      <something-magical-here>
SM>      (code using foo and bar (and blabla as well)))

SM> and get the closure we want with the docstring we want.

SM> Does anyone have an idea of what the <something-magical-here>
SM> could/should be?

Would it be crazy to make it look like a `defun' docstring?

    (lambda (foo bar)
      "My docstring about FOO and BAR"
      (code using foo and bar (and blabla as well)))

Ted




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

* Re: Constructed docstrings for closures
  2015-01-18 12:04 ` Ted Zlatanov
@ 2015-01-18 12:19   ` David Kastrup
  2015-01-18 18:15     ` Ted Zlatanov
  0 siblings, 1 reply; 9+ messages in thread
From: David Kastrup @ 2015-01-18 12:19 UTC (permalink / raw)
  To: emacs-devel

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Fri, 16 Jan 2015 11:18:26 -0500 Stefan Monnier
> <monnier@IRO.UMontreal.CA> wrote:
>
> SM> I'd like to lift this restriction by offering a new feature that lets us
> SM> do something like:
>
> SM>    (lambda (foo bar)
> SM>      <something-magical-here>
> SM>      (code using foo and bar (and blabla as well)))
>
> SM> and get the closure we want with the docstring we want.
>
> SM> Does anyone have an idea of what the <something-magical-here>
> SM> could/should be?
>
> Would it be crazy to make it look like a `defun' docstring?
>
>     (lambda (foo bar)
>       "My docstring about FOO and BAR"
>       (code using foo and bar (and blabla as well)))

Uh, that one has worked for decades already.  The point was that the
docstring was to be _computed_ from a variable in the enclosing scope.

-- 
David Kastrup



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

* Re: Constructed docstrings for closures
  2015-01-18 12:19   ` David Kastrup
@ 2015-01-18 18:15     ` Ted Zlatanov
  0 siblings, 0 replies; 9+ messages in thread
From: Ted Zlatanov @ 2015-01-18 18:15 UTC (permalink / raw)
  To: emacs-devel

On Sun, 18 Jan 2015 13:19:25 +0100 David Kastrup <dak@gnu.org> wrote: 

DK> Ted Zlatanov <tzz@lifelogs.com> writes:
>> Would it be crazy to make it look like a `defun' docstring?
>> 
>> (lambda (foo bar)
>> "My docstring about FOO and BAR"
>> (code using foo and bar (and blabla as well)))

DK> Uh, that one has worked for decades already.  The point was that the
DK> docstring was to be _computed_ from a variable in the enclosing scope.

I had honestly never seen that in Emacs Lisp code, thanks for letting me
know (and sorry for the stupidity on my part). FWIW, I like Lars'
approach because it keeps things inside the lambda.

Ted




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

end of thread, other threads:[~2015-01-18 18:15 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-01-16 16:18 Constructed docstrings for closures Stefan Monnier
2015-01-16 16:46 ` David Kastrup
2015-01-16 16:51 ` Lars Magne Ingebrigtsen
2015-01-16 16:52   ` Lars Magne Ingebrigtsen
2015-01-16 20:54     ` Stefan Monnier
2015-01-16 23:07       ` Artur Malabarba
2015-01-18 12:04 ` Ted Zlatanov
2015-01-18 12:19   ` David Kastrup
2015-01-18 18:15     ` Ted Zlatanov

Code repositories for project(s) associated with this public inbox

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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).