You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
458 lines
10 KiB
458 lines
10 KiB
\input texinfo @c -*- texinfo -*- |
|
@c %**start of header |
|
@setfilename dash.info |
|
@settitle dash |
|
@documentencoding UTF-8 |
|
@documentlanguage en |
|
@syncodeindex fn cp |
|
@dircategory Emacs |
|
@direntry |
|
* Dash: (dash.info). A modern list library for GNU Emacs |
|
@end direntry |
|
@c %**end of header |
|
|
|
@copying |
|
|
|
This manual is for @code{dash.el} version 2.12.1. |
|
|
|
Copyright © 2012-2015 Magnar Sveen |
|
|
|
@quotation |
|
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 @uref{https://www.gnu.org/licenses/}. |
|
@end quotation |
|
@end copying |
|
|
|
@finalout |
|
@titlepage |
|
@title Dash |
|
@author Magnar Sveen |
|
@page |
|
@vskip 0pt plus 1filll |
|
@insertcopying |
|
@end titlepage |
|
|
|
@contents |
|
|
|
@ifnottex |
|
@node Top |
|
@top dash |
|
@insertcopying |
|
@end ifnottex |
|
|
|
@menu |
|
* Installation:: |
|
* Functions:: |
|
* Development:: |
|
* Index:: |
|
|
|
@detailmenu |
|
--- The Detailed Node Listing --- |
|
|
|
Installation |
|
|
|
* Using in a package:: |
|
* Fontification of special variables:: |
|
|
|
Functions |
|
|
|
@c [[ function-nodes ]] |
|
|
|
Development |
|
|
|
* Contribute:: How to contribute |
|
* Changes:: List of significant changes by version |
|
* Contributors:: List of contributors |
|
@end detailmenu |
|
@end menu |
|
|
|
|
|
|
|
@node Installation |
|
@chapter Installation |
|
|
|
It's available on @uref{https://elpa.gnu.org/, GNU ELPA} and |
|
@uref{https://melpa.org/, MELPA}; use @code{M-x package-install}: |
|
|
|
@table @kbd |
|
@item M-x package-install @key{RET} dash |
|
Install the dash library. |
|
@end table |
|
|
|
@table @kbd |
|
@item M-x package-install @key{RET} dash-functional |
|
Optional, if you want the function combinators. |
|
@end table |
|
|
|
Alternatively, you can just dump @verb{~dash.el~} or |
|
@verb{~dash-functional.el~} in your load path somewhere. |
|
|
|
@menu |
|
* Using in a package:: |
|
* Fontification of special variables:: |
|
@end menu |
|
|
|
@node Using in a package |
|
@section Using in a package |
|
|
|
Add this to the big comment block at the top: |
|
|
|
@lisp |
|
;; Package-Requires: ((dash "2.12.1")) |
|
@end lisp |
|
|
|
@noindent To get function combinators: |
|
|
|
@lisp |
|
;; Package-Requires: ((dash "2.12.1") (dash-functional "1.2.0") (emacs "24")) |
|
@end lisp |
|
|
|
@node Fontification of special variables |
|
@section Fontification of special variables |
|
|
|
Font lock of special Dash variables (@code{it}, @code{acc}, etc.@:) in |
|
Emacs Lisp buffers can optionally be enabled with the autoloaded minor |
|
mode @code{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 |
|
@code{global-dash-fontify-mode}, either interactively or from your |
|
@code{user-init-file}: |
|
|
|
@lisp |
|
(global-dash-fontify-mode) |
|
@end lisp |
|
|
|
@node Functions |
|
@chapter Functions |
|
|
|
This chapter contains reference documentation for the dash |
|
@abbr{application programming interface,API}. 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. |
|
|
|
For instance, while @code{-map} takes a function to map over the list, |
|
one can also use the anaphoric form with double dashes - which will |
|
then be executed with @code{it} exposed as the list item. Here's an |
|
example: |
|
|
|
@lisp |
|
(-map (lambda (n) (* n n)) '(1 2 3 4)) ;; normal version |
|
|
|
(--map (* it it) '(1 2 3 4)) ;; anaphoric version |
|
@end lisp |
|
|
|
@noindent Of course, the original can also be written like |
|
|
|
@lisp |
|
(defun square (n) (* n n)) |
|
|
|
(-map 'square '(1 2 3 4)) |
|
@end lisp |
|
|
|
@noindent which demonstrates the usefulness of both versions. |
|
|
|
@menu |
|
@c [[ function-nodes ]] |
|
@end menu |
|
|
|
@c [[ function-docs ]] |
|
|
|
@node Development |
|
@chapter Development |
|
|
|
The dash repository is hosted on GitHub: |
|
@uref{https://github.com/magnars/dash.el} |
|
|
|
@menu |
|
* Contribute:: How to contribute |
|
* Changes:: 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 tests in @verb{~dev/examples.el~}, so remember to add |
|
tests for your function, or it might get broken later. |
|
|
|
Run the tests with @code{./run-tests.sh}. Create the docs with |
|
@code{./create-docs.sh}. 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: |
|
|
|
@verbatim |
|
cp pre-commit.sh .git/hooks/pre-commit |
|
@end verbatim |
|
|
|
Oh, and don't edit @file{README.md} directly, it is auto-generated. |
|
Change @file{readme-template.md} or @file{examples-to-docs.el} |
|
instead. The same goes for the info manual. |
|
|
|
@node Changes |
|
@section Changes |
|
|
|
@noindent Changes in 2.10: |
|
|
|
@itemize |
|
@item |
|
Add @code{-let} destructuring to @code{-if-let} and @code{-when-let} |
|
(Fredrik Bergroth) |
|
@end itemize |
|
|
|
@noindent Changes in 2.9: |
|
|
|
@itemize |
|
@item |
|
Add @code{-let}, @code{-let*} and @code{-lambda} with destructuring |
|
@item |
|
Add @code{-tree-seq} and @code{-tree-map-nodes} |
|
@item |
|
Add @code{-non-nil} |
|
@item |
|
Add @code{-fix} |
|
@item |
|
Add @code{-fixfn} (dash-functional 1.2) |
|
@item |
|
Add @code{-copy} (Wilfred Hughes) |
|
@end itemize |
|
|
|
@noindent Changes in 2.8: |
|
|
|
@itemize |
|
@item |
|
Add @code{-butlast} |
|
@end itemize |
|
|
|
@noindent Changes in 2.7: |
|
|
|
@itemize |
|
@item |
|
@code{-zip} now supports more than two lists (Steve Lamb) |
|
@item |
|
Add @code{-cycle}, @code{-pad}, @code{-annotate}, @code{-zip-fill} |
|
(Steve Lamb) |
|
@item |
|
Add @code{-table}, @code{-table-flat} (finite cartesian product) |
|
@item |
|
Add @code{-flatten-n} |
|
@item |
|
@code{-slice} now supports "step" argument |
|
@item |
|
Add functional combinators @code{-iteratefn}, @code{-prodfn} |
|
@item |
|
Add @code{-replace}, @code{-splice}, @code{-splice-list} which |
|
generalize @code{-replace-at} and @code{-insert-at} |
|
@item |
|
Add @code{-compose}, @code{-iteratefn} and @code{-prodfn} |
|
(dash-functional 1.1) |
|
@end itemize |
|
|
|
@noindent Changes in 2.6: |
|
|
|
@itemize |
|
@item |
|
Add @code{-is-prefix-p}, @code{-is-suffix-p}, @code{-is-infix-p} |
|
(Matus Goljer) |
|
@item |
|
Add @code{-iterate}, @code{-unfold} (Matus Goljer) |
|
@item |
|
Add @code{-split-on}, @code{-split-when} (Matus Goljer) |
|
@item |
|
Add @code{-find-last-index} (Matus Goljer) |
|
@item |
|
Add @code{-list} (Johan Andersson) |
|
@end itemize |
|
|
|
@noindent Changes in 2.5: |
|
|
|
@itemize |
|
@item |
|
Add @code{-same-items?} (Johan Andersson) |
|
@item |
|
A few bugfixes |
|
@end itemize |
|
|
|
@noindent Changes in 2.4: |
|
|
|
@itemize |
|
@item |
|
Add @code{-snoc} (Matus Goljer) |
|
@item |
|
Add @code{-replace-at}, @code{-update-at}, @code{-remove-at}, and |
|
@code{-remove-at-indices} (Matus Goljer) |
|
@end itemize |
|
|
|
@noindent Changes in 2.3: |
|
|
|
@itemize |
|
@item |
|
Add tree operations (Matus Goljer) |
|
@item |
|
Make font-lock optional |
|
@end itemize |
|
|
|
@noindent Changes in 2.2: |
|
|
|
@itemize |
|
@item |
|
Add @code{-compose} (Christina Whyte) |
|
@end itemize |
|
|
|
@noindent Changes in 2.1: |
|
|
|
@itemize |
|
@item |
|
Add indexing operations (Matus Goljer) |
|
@end itemize |
|
|
|
@noindent Changes in 2.0: |
|
|
|
@itemize |
|
@item |
|
Split out @code{dash-functional.el} (Matus Goljer) |
|
@item |
|
Add @code{-andfn}, @code{-orfn}, @code{-not}, @code{-cut}, |
|
@code{-const}, @code{-flip} and @code{-on}. (Matus Goljer) |
|
@item |
|
Fix @code{-min}, @code{-max}, @code{-min-by} and @code{-max-by} (Matus |
|
Goljer) |
|
@end itemize |
|
|
|
@noindent Changes in 1.8: |
|
|
|
@itemize |
|
@item |
|
Add @code{-first-item} and @code{-last-item} (Wilfred Hughes) |
|
@end itemize |
|
|
|
@noindent Changes in 1.7: |
|
|
|
@itemize |
|
@item |
|
Add @code{-rotate} (Matus Goljer) |
|
@end itemize |
|
|
|
@noindent Changes in 1.6: |
|
|
|
@itemize |
|
@item |
|
Add @code{-min}, @code{-max}, @code{-min-by} and @code{-max-by} (Johan |
|
Andersson) |
|
@end itemize |
|
|
|
@noindent Changes in 1.5: |
|
|
|
@itemize |
|
@item |
|
Add @code{-sum} and @code{-product} (Johan Andersson) |
|
@end itemize |
|
|
|
@noindent Changes in 1.4: |
|
|
|
@itemize |
|
@item |
|
Add @code{-sort} |
|
@item |
|
Add @code{-reduce-r} (Matus Goljer) |
|
@item |
|
Add @code{-reduce-r-from} (Matus Goljer) |
|
@end itemize |
|
|
|
@noindent Changes in 1.3: |
|
|
|
@itemize |
|
@item |
|
Add @code{-partition-in-steps} |
|
@item |
|
Add @code{-partition-all-in-steps} |
|
@end itemize |
|
|
|
@noindent Changes in 1.2: |
|
|
|
@itemize |
|
@item |
|
Add @code{-last} (Matus Goljer) |
|
@item |
|
Add @code{-insert-at} (Emanuel Evans) |
|
@item |
|
Add @code{-when-let} and @code{-if-let} (Emanuel Evans) |
|
@item |
|
Add @code{-when-let*} and @code{-if-let*} (Emanuel Evans) |
|
@item |
|
Some bugfixes |
|
@end itemize |
|
|
|
@node Contributors |
|
@section Contributors |
|
|
|
@itemize |
|
@item |
|
@uref{https://github.com/Fuco1,Matus Goljer} contributed lots of |
|
features and functions. |
|
@item |
|
@uref{https://github.com/tkf,Takafumi Arakaki} contributed |
|
@code{-group-by}. |
|
@item |
|
@uref{https://github.com/tali713,tali713} is the author of |
|
@code{-applify}. |
|
@item |
|
@uref{https://github.com/vemv,Víctor M. Valenzuela} contributed |
|
@code{-repeat}. |
|
@item |
|
@uref{https://github.com/nicferrier,Nic Ferrier} contributed |
|
@code{-cons*}. |
|
@item |
|
@uref{https://github.com/Wilfred,Wilfred Hughes} contributed |
|
@code{-slice}, @code{-first-item} and @code{-last-item}. |
|
@item |
|
@uref{https://github.com/shosti,Emanuel Evans} contributed |
|
@code{-if-let}, @code{-when-let} and @code{-insert-at}. |
|
@item |
|
@uref{https://github.com/rejeep,Johan Andersson} contributed |
|
@code{-sum}, @code{-product} and @code{-same-items?} |
|
@item |
|
@uref{https://github.com/kurisuwhyte,Christina Whyte} contributed |
|
@code{-compose} |
|
@item |
|
@uref{https://github.com/steventlamb,Steve Lamb} contributed |
|
@code{-cycle}, @code{-pad}, @code{-annotate}, @code{-zip-fill} and an |
|
n-ary version of @code{-zip}. |
|
@item |
|
@uref{https://github.com/fbergroth,Fredrik Bergroth} made the |
|
@code{-if-let} family use @code{-let} destructuring and improved |
|
script for generating documentation. |
|
@item |
|
@uref{https://github.com/holomorph,Mark Oteiza} contributed the |
|
script to create an info manual. |
|
@item |
|
@uref{https://github.com/wasamasa,Vasilij Schneidermann} contributed |
|
@code{-some}. |
|
@item |
|
@uref{https://github.com/occidens,William West} made @code{-fixfn} |
|
more robust at handling floats. |
|
@end itemize |
|
|
|
Thanks! |
|
|
|
@node Index |
|
@unnumbered Index |
|
|
|
@printindex cp |
|
|
|
@bye
|
|
|