Dash
****

This manual is for Dash version .

Copyright © 2012--2021 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License,'' and no Front-Cover Texts or Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Installation
************

Dash is available on GNU ELPA (https://elpa.gnu.org/) and MELPA (https://melpa.org/), and can be installed with the standard command package-install (see Package Installation (The GNU Emacs Manual)).

M-x package-install RET dash RET
     Install the Dash library.

M-x package-install RET dash-functional RET
     Install an optional library of additional function combinators.

Alternatively, you can just dump dash.el or dash-functional.el in your load path somewhere.

Using in a package
==================

If you use Dash in your own package, be sure to list it as a dependency in the library's headers as follows (see Library Headers (The Emacs Lisp Reference Manual)).

     ;; Package-Requires: ((dash ""))

The same goes for the dash-functional.el library of function combinators:

     ;; Package-Requires: ((dash "") (dash-functional ""))

Fontification of special variables
==================================

The autoloaded minor mode dash-fontify-mode is provided for optional fontification of anaphoric Dash variables (it, acc, etc.) in Emacs Lisp buffers using search-based Font Lock (see Font Lock (The GNU Emacs Manual)).  In older Emacs versions which do not dynamically detect macros, the minor mode also fontifies calls to Dash macros.

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 Info Lookup (The GNU Emacs Manual)).  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
*********

This chapter contains reference documentation for the Dash API (Application Programming Interface).  The names of all public functions defined in the library are prefixed with a dash character (-).

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.

For instance, while the function -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.

     ;; Normal version.
     (-map (lambda (n) (* n n)) '(1 2 3 4))
         => (1 4 9 16)

     ;; Anaphoric version.
     (--map (* it it) '(1 2 3 4))
         => (1 4 9 16)

The normal version can, of course, also be written as in the following example, which demonstrates the utility of both versions.

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

     (-map #'my-square '(1 2 3 4))
         => (1 4 9 16)

Development
***********

The Dash repository is hosted on GitHub at https://github.com/magnars/dash.el.

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 they may get broken later.

Run the tests with make check.  Regenerate the docs with make docs.  Contributors are encouraged to install these commands as a Git pre-commit hook, so that the tests are always running and the docs are always in sync:

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

Oh, and don't edit README.md or dash.texi directly, as they are auto-generated.  Instead, change their respective templates readme-template.md or dash-template.texi.

To ensure that Dash 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 Copyright Assignment (The GNU Emacs Manual).

Change log
==========

Changes in 2.17:

       * Sped up -uniq by using hash-tables when possible (Zhu Zihao).

       * Fixed -inits to be non-destructive (Zach Shaftel).

       * Fixed indent rules for -some-> and family (Wouter Bolsterlee).

       * Added -zip-lists which always returns a list of proper lists, even for two input lists (see issue #135).

Changes in 2.16:

       * Added --doto, anaphoric version of -doto.

       * Aliased -cons-pair-p to -cons-pair?.

       * Generalized -rotate for |N| greater than the length of the list (Brian Leung).

       * Added a mechanism to extend destructuring with custom matchers (Ivan Yonchovski).

Changes in 2.15:

     This release brought new destructuring features, some new control flow functions, and performance optimizations.

       * Added -setq with destructuring binding support similar to the -let family.

       * Added smarter key destructuring in -let and friends where variables are auto-derived from keys.

       * Allowed -let bindings without a source value form.

       * Added -each-r and -each-r-while (Paul Pogonyshev).

       * Added -common-suffix (Basil L. Contovounesios).

       * Improved performance of folds (-reduce and friends) (Basil L. Contovounesios).

Changes in 2.14:

     This release retired support for Emacs 23.

       * Added Edebug support for threading macros (Wilfred Hughes).

       * Added -unzip.

       * Added support for -first-item and -last-item as place forms (see Generalized Variables (The Emacs Lisp Reference Manual)).

       * Added -powerset and -permutations (Mark Oteiza).

       * Added -as-> for threading a named variable (Zachary Kanfer).

       * Added -partition-after-pred, -partition-before-pred, -partition-after-item, and -partition-before-item (Zachary Kanfer).

       * Fixed a bug in -any-p and friends testing for null on lists containing nil.

       * Fixed infinite loop bug in -zip and -interleave when called with empty input.

       * Added -second-item through -fifth-item as alternatives to nth (Wilfred Hughes).

       * Added -tails and -inits.

       * Added -running-sum and -running-product.

       * Added the -reductions[-r][-from] family of functions (like -reduce but collecting intermediate results).

       * Added -common-prefix (Basil L. Contovounesios).

Changes in 2.13:

       * -let now supports &alist destructuring.

       * Various performance improvements.

       * -zip might change in a future release to always return a list of proper lists.  Added -zip-pair for users who explicitly want the old behavior.

       * Enabled lexical binding in dash.el for Emacs versions 24 or newer.

       * Added -select-column and -select-columns.

       * Fixed -map-last and --remove-last to be non-destructive.

       * Added -each-indexed and --each-indexed.

       * Added -take-last and -drop-last.

       * Added the -doto macro.

       * -cut <> is now treated as a function, consistent with SRFI 26 (https://srfi.schemers.org/srfi-26/srfi-26.html).

Changes in 2.12:

       * Added GNU ELPA support (Phillip Lord).

       * Added -some->, -some->>, and -some--> macros (Cam Saul).

       * -is-suffix? is now non-destructive.

       * Faster hash table implementation for -union.

       * Improvements to docstrings and examples.

Changes in 2.11:

       * Lots of clean up w.r.t. byte compilation, debug macros, and tests.

Changes in 2.10:

       * Added -let destructuring to -if-let and -when-let (Fredrik Bergroth).

Changes in 2.9:

       * Added -let, -let*, and -lambda with destructuring.

       * Added -tree-seq and -tree-map-nodes.

       * Added -non-nil.

       * Added -fix.

       * Added -fixfn (dash-functional version 1.2).

       * Added -copy (Wilfred Hughes).

Changes in 2.8:

       * Added -butlast.

Changes in 2.7:

       * -zip now supports more than two lists (Steve Lamb).

       * Added -cycle, -pad, -annotate, and -zip-fill (Steve Lamb).

       * Added -table, -table-flat (finite Cartesian product).

       * Added -flatten-n.

       * -slice now supports a ``step'' argument.

       * Added functional combinators -iteratefn and -prodfn.

       * Added -replace, -splice, and -splice-list which generalize -replace-at and -insert-at.

       * Added -compose, -iteratefn, and -prodfn (dash-functional version 1.1).

Changes in 2.6:

       * Added -is-prefix-p, -is-suffix-p, and -is-infix-p (Matus Goljer).

       * Added -iterate and -unfold (Matus Goljer).

       * Added -split-on and -split-when (Matus Goljer).

       * Added -find-last-index (Matus Goljer).

       * Added -list (Johan Andersson).

Changes in 2.5:

       * Added -same-items? (Johan Andersson).

       * Various bugfixes.

Changes in 2.4:

       * Added -snoc (Matus Goljer).

       * Added -replace-at, -update-at, -remove-at, and -remove-at-indices (Matus Goljer).

Changes in 2.3:

       * Added tree operations (Matus Goljer).

       * Made Font Lock optional.

Changes in 2.2:

       * Added -compose (Christina Whyte).

Changes in 2.1:

       * Added indexing operations (Matus Goljer).

Changes in 2.0:

       * Split out dash-functional.el (Matus Goljer).

       * Added -andfn, -orfn, -not, -cut, -const, -flip, and -on (Matus Goljer).

       * Fixed -min, -max, -min-by, and -max-by (Matus Goljer).

Changes in 1.8:

       * Added -first-item and -last-item (Wilfred Hughes).

Changes in 1.7:

       * Added -rotate (Matus Goljer).

Changes in 1.6:

       * Added -min, -max, -min-by, and -max-by (Johan Andersson).

Changes in 1.5:

       * Added -sum and -product (Johan Andersson).

Changes in 1.4:

       * Added -sort.

       * Added -reduce-r (Matus Goljer).

       * Added -reduce-r-from (Matus Goljer).

Changes in 1.3:

       * Added -partition-in-steps.

       * Added -partition-all-in-steps.

Changes in 1.2:

       * Added -last (Matus Goljer).

       * Added -insert-at (Emanuel Evans).

       * Added -when-let and -if-let (Emanuel Evans).

       * Added -when-let* and -if-let* (Emanuel Evans).

       * Various bugfixes.

Contributors
============

  * Matus Goljer (https://github.com/Fuco1) contributed lots of features and functions.

  * Takafumi Arakaki (https://github.com/tkf) contributed -group-by.

  * tali713 (https://github.com/tali713) is the author of -applify.

  * Víctor M. Valenzuela (https://github.com/vemv) contributed -repeat.

  * Nic Ferrier (https://github.com/nicferrier) contributed -cons*.

  * Wilfred Hughes (https://github.com/Wilfred) contributed -slice, -first-item, and -last-item.

  * Emanuel Evans (https://github.com/shosti) contributed -if-let, -when-let, and -insert-at.

  * Johan Andersson (https://github.com/rejeep) contributed -sum, -product, and -same-items?.

  * Christina Whyte (https://github.com/kurisuwhyte) contributed -compose.

  * Steve Lamb (https://github.com/steventlamb) contributed -cycle, -pad, -annotate, -zip-fill, and a variadic version of -zip.

  * Fredrik Bergroth (https://github.com/fbergroth) made the -if-let family use -let destructuring and improved the script for generating documentation.

  * Mark Oteiza (https://github.com/holomorph) contributed the script to create an Info manual.

  * Vasilij Schneidermann (https://github.com/wasamasa) contributed -some.

  * William West (https://github.com/occidens) made -fixfn more robust at handling floats.

  * Cam Saul (https://github.com/camsaul) contributed -some->, -some->>, and -some-->.

  * Basil L. Contovounesios (https://github.com/basil-conto) contributed -common-prefix.

  * Paul Pogonyshev (https://github.com/doublep) contributed -each-r and -each-r-while.

Thanks!

New contributors are very welcome.  See Contribute.

GNU Free Documentation License
******************************

     [file fdl.texi not included]

GNU General Public License
**************************

     [file gpl.texi not included]