readme-template.md

dash.el

A modern list API for Emacs. No 'cl required.

See the end of the file for license conditions.

Contents

• Change log
• Installation
• Functions
• Contribute
• Contributors
• License

Change log

See the NEWS.md file.

Installation

Dash is available on GNU ELPA, GNU-devel ELPA, and MELPA, and can be installed with the standard command package-install:

M-x package-install RET dash RET

See (info "(emacs) Package Installation").

Alternatively, you can just dump dash.el in your load-path somewhere. See (info "(emacs) Lisp Libraries").

Using in a package

Add something like this to the library's headers:

;; Package-Requires: ((dash "[[ dash-version ]]"))

See (info "(elisp) Library Headers").

Fontification of special variables

Font lock of special Dash variables (it, acc, etc.) in Emacs Lisp buffers can optionally be enabled with the autoloaded minor mode dash-fontify-mode. In older Emacs versions which do not dynamically detect macros, the minor mode also fontifies Dash macro calls.

To automatically enable the minor mode in all Emacs Lisp buffers, just call its autoloaded global counterpart global-dash-fontify-mode, either interactively or from your user-init-file:

(global-dash-fontify-mode)

Info symbol lookup

While editing Elisp files, you can use C-h S (info-lookup-symbol) to look up Elisp symbols in the relevant Info manuals (see (emacs) Info Lookup). To enable the same for Dash symbols, use the command dash-register-info-lookup. It can be called directly when needed, or automatically from your user-init-file. For example:

(with-eval-after-load 'info-look
  (dash-register-info-lookup))

Functions

All functions and constructs in the library use a dash (-) prefix.

The library also provides anaphoric macro versions of functions where that makes sense. The names of these macros are prefixed with two dashes (--) instead of one.

While -map applies a function to each element of a list, its anaphoric counterpart --map evaluates a form with the local variable it temporarily bound to the current list element instead. For example:

(-map (lambda (n) (* n n)) '(1 2 3 4)) ; Normal version.
(--map (* it it) '(1 2 3 4))           ; Anaphoric version.

The normal version can of course also be written as follows:

(defun my-square (n)
  "Return N multiplied by itself."
  (* n n))

(-map #'my-square '(1 2 3 4))

This demonstrates the utility of both versions. [[ function-list ]]

[[ function-docs ]]

Contribute

Yes, please do. Pure functions in the list manipulation realm only, please. There's a suite of examples/tests in dev/examples.el, so remember to add tests for your additions, or I might break them later.

You'll find the repo at:

https://github.com/magnars/dash.el

Run the tests with:

make check

Regenerate the docs with:

make docs

I highly recommend that you install these as a pre-commit hook, so that the tests are always running and the docs are always in sync:

cp dev/pre-commit.sh .git/hooks/pre-commit

Oh, and don't edit README.md or dash.texi directly; they are auto-generated. Change readme-template.md or dash-template.texi instead, respectively.

To ensure that dash.el can be distributed with GNU ELPA or Emacs, we require that all contributors assign copyright to the Free Software Foundation. For more on this, see (info "(emacs) Copyright Assignment").

Contributors

• Matus Goljer contributed lots of features and functions.
• Takafumi Arakaki contributed -group-by.
• tali713 is the author of -applify.
• Víctor M. Valenzuela contributed -repeat.
• Nic Ferrier contributed -cons*.
• Wilfred Hughes contributed -slice, -first-item, and -last-item.
• Emanuel Evans contributed -if-let, -when-let, and -insert-at.
• Johan Andersson contributed -sum, -product, and -same-items?.
• Christina Whyte contributed -compose.
• Steve Lamb contributed -cycle, -pad, -annotate, -zip-fill, and a variadic version of -zip.
• Fredrik Bergroth made the -if-let family use -let destructuring and improved the script for generating documentation.
• Mark Oteiza contributed -iota and the script to create an Info manual.
• Vasilij Schneidermann contributed -some.
• William West made -fixfn more robust at handling floats.
• Cam Saul contributed -some->, -some->>, and -some-->.
• Basil L. Contovounesios contributed -common-prefix, -common-suffix, and various other improvements.
• Paul Pogonyshev contributed -each-r and -each-r-while.

Thanks!

New contributors are very welcome. See the Contribute section above.

License

Copyright (C) 2012-2024 Free Software Foundation, Inc.

Author: Magnar Sveen magnars@gmail.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.