Re: dash.el [was: Re: Imports / inclusion of s.el into Emacs]

[Philippe Vaucher]

> Thanks for showing me examples of dash.el.  A lot of these facilities
> seem useful.  I would very much like to see the _documentation_ for how
> to use it.

Go to https://github.com/magnars/dash.el#functions for its
documentation. As soon as you load that page you'd see the
documentation, if not scroll a bit down until you read the text.

> First, these all seem to be macros, right?

Some of them are, some others not.

Usually the ones that have double dashes at the beginning are macros, yes.

> Why do some names start with a single dash and some with a double dash?

I think its simpler for me to copy paste the documentation:

All functions and constructs in the library are prefixed with a dash (-).

There are also anaphoric versions of functions where that makes sense,
prefixed with two dashes instead of one.

While -map takes a function to map over the list, you can also use the
anaphoric form with double dashes - which will then be executed with
it exposed as the list item. Here's an example:

(-map (lambda (n) (* n n)) '(1 2 3 4)) ;; normal version
(--map (* it it) '(1 2 3 4)) ;; anaphoric version

of course the original can also be written like

(defun square (n) (* n n))
(-map 'square '(1 2 3 4))

which demonstrates the usefulness of both versions.


> About --map-when:
>
>   > (let ((lst '(1 2 3 4)))
>   >   (pp (--map-when (= it 2) 17 lst))
>   >   (pp (mapcar (lambda (it) (if (= it 2) 17 it)) lst)))
>
> The map-when version was not self-evident to me.
> I had to read the mapcar version to understand its meaning.
> Once I did that, it made sense, and I can see that it is useful.
> I think we should add this to Emacs, but with a couple of changes.
>
> * Call it 'map-when' -- why use dashes?

Yes, if in Emacs it'll probably have another name. We could also put
in seq as seq-map-when.

>   > I was going to make an example with `-flatten` but I think this page
>   > is better showing my point:
>   > 
> https://stackoverflow.com/questions/969067/name-of-this-function-in-built-in-emacs-lisp-library
>
> I will fetch that page and look at it.

The point was that until very recently (27.1) there was no flatten
function, which is something almost every language has.

>     (->> '(1 2 3) (-map 'square) (-remove 'even?)) ;; => '(1 9)
>
> Is '-map' just another name for 'mapcar'?

Yes