dash.el/dash-template.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename dash.info
@set DASHVER @c [[ dash-version ]]
@set DASHFNVER @c [[ dash-functional-version ]]
@settitle Dash: A modern list library for GNU Emacs.
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
This manual is for Dash version @value{DASHVER}.

Copyright @copyright{} 2012--2021 Free Software Foundation, Inc.

@quotation
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''.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Dash: (dash.info).    A modern list library for GNU Emacs.
@end direntry

@titlepage
@title Dash Manual
@subtitle For Dash Version @value{DASHVER}.
@author Magnar Sveen
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Dash

@insertcopying
@end ifnottex

@menu
* Installation::        Installing and configuring Dash.
* Functions::           Dash API reference.
* Development::         Contributing to Dash development.

Appendices

* FDL::                 The license for this documentation.
* GPL::                 Conditions for copying and changing Dash.
* Index::               Index including functions and macros.

@detailmenu
 --- The Detailed Node Listing ---

Installation

* Using in a package::  Listing Dash as a package dependency.
* Fontification of special variables::  Font Lock of anaphoric macro variables.
* Info symbol lookup::  Looking up Dash symbols in this manual.

Functions

@c [[ function-nodes ]]

Development

* Contribute::          How to contribute.
* Change log::          List of significant changes by version.
* Contributors::        List of contributors.
@end detailmenu
@end menu

@node Installation
@chapter Installation

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

@table @kbd
@item M-x package-install @key{RET} dash @key{RET}
Install the Dash library.

@item M-x package-install @key{RET} dash-functional @key{RET}
Install an optional library of additional function combinators.
@end table

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

@menu
* Using in a package::  Listing Dash as a package dependency.
* Fontification of special variables::  Font Lock of anaphoric macro variables.
* Info symbol lookup::  Looking up Dash symbols in this manual.
@end menu

@node Using in a package
@section 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 (@pxref{Library
Headers,,, elisp, The Emacs Lisp Reference Manual}).

@lisp
;; Package-Requires: ((dash "@value{DASHVER}"))
@end lisp

The same goes for the @file{dash-functional.el} library of function
combinators:

@lisp
;; Package-Requires: ((dash "@value{DASHVER}") (dash-functional "@value{DASHFNVER}"))
@end lisp

@node Fontification of special variables
@section Fontification of special variables

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

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

@lisp
(global-dash-fontify-mode)
@end lisp

@node Info symbol lookup
@section Info symbol lookup

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

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

@node Functions
@chapter Functions

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

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

For instance, while the function @code{-map} applies a function to
each element of a list, its anaphoric counterpart @code{--map}
evaluates a form with the local variable @code{it} temporarily bound
to the current list element instead.

@lisp
@group
;; Normal version.
(-map (lambda (n) (* n n)) '(1 2 3 4))
    @result{} (1 4 9 16)
@end group

@group
;; Anaphoric version.
(--map (* it it) '(1 2 3 4))
    @result{} (1 4 9 16)
@end group
@end lisp

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

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

(-map #'my-square '(1 2 3 4))
    @result{} (1 4 9 16)
@end group
@end lisp

@menu
@c [[ function-nodes ]]
@end menu
@c [[ function-docs ]]

@node Development
@chapter Development

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

@menu
* Contribute::          How to contribute.
* Change log::          List of significant changes by version.
* Contributors::        List of contributors.
@end menu

@node Contribute
@section Contribute

Yes, please do.  Pure functions in the list manipulation realm only,
please.  There's a suite of examples/tests in @file{dev/examples.el},
so remember to add tests for your additions, or they may get broken
later.

Run the tests with @samp{make check}.  Regenerate the docs with
@samp{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:

@example
$ cp dev/pre-commit.sh .git/hooks/pre-commit
@end example

Oh, and don't edit @file{README.md} or @file{dash.texi} directly, as
they are auto-generated.  Instead, change their respective templates
@file{readme-template.md} or @file{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, @pxref{Copyright Assignment,,, emacs,
The GNU Emacs Manual}.

@node Change log
@section Change log

@table @asis
@item Changes in 2.17:

@itemize
@item
Sped up @code{-uniq} by using hash-tables when possible (Zhu Zihao).
@item
Fixed @code{-inits} to be non-destructive (Zach Shaftel).
@item
Fixed indent rules for @code{-some->} and family (Wouter Bolsterlee).
@item
Added @code{-zip-lists} which always returns a list of proper lists,
even for two input lists (see issue #135).
@end itemize

@item Changes in 2.16:

@itemize
@item
Added @code{--doto}, anaphoric version of @code{-doto}.
@item
Aliased @code{-cons-pair-p} to @code{-cons-pair?}.
@item
Generalized @code{-rotate} for @math{|@var{n}|} greater than the
length of the list (Brian Leung).
@item
Added a mechanism to extend destructuring with custom matchers (Ivan
Yonchovski).
@end itemize

@item Changes in 2.15:

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

@itemize
@item
Added @code{-setq} with destructuring binding support similar to the
@code{-let} family.
@item
Added smarter key destructuring in @code{-let} and friends where
variables are auto-derived from keys.
@item
Allowed @code{-let} bindings without a source value form.
@item
Added @code{-each-r} and @code{-each-r-while} (Paul Pogonyshev).
@item
Added @code{-common-suffix} (Basil L. Contovounesios).
@item
Improved performance of folds (@code{-reduce} and friends) (Basil L.
Contovounesios).
@end itemize

@item Changes in 2.14:

This release retired support for Emacs 23.

@itemize
@item
Added Edebug support for threading macros (Wilfred Hughes).
@item
Added @code{-unzip}.
@item
Added support for @code{-first-item} and @code{-last-item} as place
forms (@pxref{Generalized Variables,,, elisp, The Emacs Lisp Reference
Manual}).
@item
Added @code{-powerset} and @code{-permutations} (Mark Oteiza).
@item
Added @code{-as->} for threading a named variable (Zachary Kanfer).
@item
Added @code{-partition-after-pred}, @code{-partition-before-pred},
@code{-partition-after-item}, and @code{-partition-before-item}
(Zachary Kanfer).
@item
Fixed a bug in @code{-any-p} and friends testing for @code{null} on
lists containing @code{nil}.
@item
Fixed infinite loop bug in @code{-zip} and @code{-interleave} when
called with empty input.
@item
Added @code{-second-item} through @code{-fifth-item} as alternatives
to @code{nth} (Wilfred Hughes).
@item
Added @code{-tails} and @code{-inits}.
@item
Added @code{-running-sum} and @code{-running-product}.
@item
Added the @code{-reductions[-r][-from]} family of functions (like
@code{-reduce} but collecting intermediate results).
@item
Added @code{-common-prefix} (Basil L. Contovounesios).
@end itemize

@item Changes in 2.13:

@itemize
@item
@code{-let} now supports @code{&alist} destructuring.
@item
Various performance improvements.
@item
@code{-zip} might change in a future release to always return a list
of proper lists.  Added @code{-zip-pair} for users who explicitly want
the old behavior.
@item
Enabled lexical binding in @file{dash.el} for Emacs versions 24 or
newer.
@item
Added @code{-select-column} and @code{-select-columns}.
@item
Fixed @code{-map-last} and @code{--remove-last} to be non-destructive.
@item
Added @code{-each-indexed} and @code{--each-indexed}.
@item
Added @code{-take-last} and @code{-drop-last}.
@item
Added the @code{-doto} macro.
@item
@code{-cut <>} is now treated as a function, consistent with
@url{https://srfi.schemers.org/srfi-26/srfi-26.html, SRFI 26}.
@end itemize

@item Changes in 2.12:

@itemize
@item
Added GNU ELPA support (Phillip Lord).
@item
Added @code{-some->}, @code{-some->>}, and @code{-some-->} macros (Cam
Saul).
@item
@code{-is-suffix?} is now non-destructive.
@item
Faster hash table implementation for @code{-union}.
@item
Improvements to docstrings and examples.
@end itemize

@item Changes in 2.11:

@itemize
@item
Lots of clean up w.r.t. byte compilation, debug macros, and tests.
@end itemize

@item Changes in 2.10:

@itemize
@item
Added @code{-let} destructuring to @code{-if-let} and @code{-when-let}
(Fredrik Bergroth).
@end itemize

@item Changes in 2.9:

@itemize
@item
Added @code{-let}, @code{-let*}, and @code{-lambda} with
destructuring.
@item
Added @code{-tree-seq} and @code{-tree-map-nodes}.
@item
Added @code{-non-nil}.
@item
Added @code{-fix}.
@item
Added @code{-fixfn} (@samp{dash-functional} version 1.2).
@item
Added @code{-copy} (Wilfred Hughes).
@end itemize

@item Changes in 2.8:

@itemize
@item
Added @code{-butlast}.
@end itemize

@item Changes in 2.7:

@itemize
@item
@code{-zip} now supports more than two lists (Steve Lamb).
@item
Added @code{-cycle}, @code{-pad}, @code{-annotate}, and
@code{-zip-fill} (Steve Lamb).
@item
Added @code{-table}, @code{-table-flat} (finite Cartesian product).
@item
Added @code{-flatten-n}.
@item
@code{-slice} now supports a ``step'' argument.
@item
Added functional combinators @code{-iteratefn} and @code{-prodfn}.
@item
Added @code{-replace}, @code{-splice}, and @code{-splice-list} which
generalize @code{-replace-at} and @code{-insert-at}.
@item
Added @code{-compose}, @code{-iteratefn}, and @code{-prodfn}
(@samp{dash-functional} version 1.1).
@end itemize

@item Changes in 2.6:

@itemize
@item
Added @code{-is-prefix-p}, @code{-is-suffix-p}, and @code{-is-infix-p}
(Matus Goljer).
@item
Added @code{-iterate} and @code{-unfold} (Matus Goljer).
@item
Added @code{-split-on} and @code{-split-when} (Matus Goljer).
@item
Added @code{-find-last-index} (Matus Goljer).
@item
Added @code{-list} (Johan Andersson).
@end itemize

@item Changes in 2.5:

@itemize
@item
Added @code{-same-items?} (Johan Andersson).
@item
Various bugfixes.
@end itemize

@item Changes in 2.4:

@itemize
@item
Added @code{-snoc} (Matus Goljer).
@item
Added @code{-replace-at}, @code{-update-at}, @code{-remove-at}, and
@code{-remove-at-indices} (Matus Goljer).
@end itemize

@item Changes in 2.3:

@itemize
@item
Added tree operations (Matus Goljer).
@item
Made Font Lock optional.
@end itemize

@item Changes in 2.2:

@itemize
@item
Added @code{-compose} (Christina Whyte).
@end itemize

@item Changes in 2.1:

@itemize
@item
Added indexing operations (Matus Goljer).
@end itemize

@item Changes in 2.0:

@itemize
@item
Split out @file{dash-functional.el} (Matus Goljer).
@item
Added @code{-andfn}, @code{-orfn}, @code{-not}, @code{-cut},
@code{-const}, @code{-flip}, and @code{-on} (Matus Goljer).
@item
Fixed @code{-min}, @code{-max}, @code{-min-by}, and @code{-max-by}
(Matus Goljer).
@end itemize

@item Changes in 1.8:

@itemize
@item
Added @code{-first-item} and @code{-last-item} (Wilfred Hughes).
@end itemize

@item Changes in 1.7:

@itemize
@item
Added @code{-rotate} (Matus Goljer).
@end itemize

@item Changes in 1.6:

@itemize
@item
Added @code{-min}, @code{-max}, @code{-min-by}, and @code{-max-by}
(Johan Andersson).
@end itemize

@item Changes in 1.5:

@itemize
@item
Added @code{-sum} and @code{-product} (Johan Andersson).
@end itemize

@item Changes in 1.4:

@itemize
@item
Added @code{-sort}.
@item
Added @code{-reduce-r} (Matus Goljer).
@item
Added @code{-reduce-r-from} (Matus Goljer).
@end itemize

@item Changes in 1.3:

@itemize
@item
Added @code{-partition-in-steps}.
@item
Added @code{-partition-all-in-steps}.
@end itemize

@item Changes in 1.2:

@itemize
@item
Added @code{-last} (Matus Goljer).
@item
Added @code{-insert-at} (Emanuel Evans).
@item
Added @code{-when-let} and @code{-if-let} (Emanuel Evans).
@item
Added @code{-when-let*} and @code{-if-let*} (Emanuel Evans).
@item
Various bugfixes.
@end itemize
@end table

@node Contributors
@section Contributors

@itemize
@item
@url{https://github.com/Fuco1, Matus Goljer} contributed lots of
features and functions.
@item
@url{https://github.com/tkf, Takafumi Arakaki} contributed
@code{-group-by}.
@item
@url{https://github.com/tali713, tali713} is the author of
@code{-applify}.
@item
@url{https://github.com/vemv, V@'{i}ctor M. Valenzuela} contributed
@code{-repeat}.
@item
@url{https://github.com/nicferrier, Nic Ferrier} contributed
@code{-cons*}.
@item
@url{https://github.com/Wilfred, Wilfred Hughes} contributed
@code{-slice}, @code{-first-item}, and @code{-last-item}.
@item
@url{https://github.com/shosti, Emanuel Evans} contributed
@code{-if-let}, @code{-when-let}, and @code{-insert-at}.
@item
@url{https://github.com/rejeep, Johan Andersson} contributed
@code{-sum}, @code{-product}, and @code{-same-items?}.
@item
@url{https://github.com/kurisuwhyte, Christina Whyte} contributed
@code{-compose}.
@item
@url{https://github.com/steventlamb, Steve Lamb} contributed
@code{-cycle}, @code{-pad}, @code{-annotate}, @code{-zip-fill}, and a
variadic version of @code{-zip}.
@item
@url{https://github.com/fbergroth, Fredrik Bergroth} made the
@code{-if-let} family use @code{-let} destructuring and improved the
script for generating documentation.
@item
@url{https://github.com/holomorph, Mark Oteiza} contributed the
script to create an Info manual.
@item
@url{https://github.com/wasamasa, Vasilij Schneidermann} contributed
@code{-some}.
@item
@url{https://github.com/occidens, William West} made @code{-fixfn}
more robust at handling floats.
@item
@url{https://github.com/camsaul, Cam Saul} contributed @code{-some->},
@code{-some->>}, and @code{-some-->}.
@item
@url{https://github.com/basil-conto, Basil L. Contovounesios} contributed
@code{-common-prefix}.
@item
@url{https://github.com/doublep, Paul Pogonyshev} contributed
@code{-each-r} and @code{-each-r-while}.
@end itemize

Thanks!

New contributors are very welcome.  @xref{Contribute}.

@c Appendices.

@node FDL
@appendix GNU Free Documentation License
@include doc/fdl.texi

@node GPL
@appendix GNU General Public License
@include doc/gpl.texi

@node Index
@unnumbered Index
@printindex fn

@bye