readme-template.md (7734B)
1 [](https://github.com/magnars/dash.el/actions/workflows/test.yml) 2 [](https://elpa.gnu.org/packages/dash.html) 3 [](https://elpa.gnu.org/devel/dash.html) 4 [](https://stable.melpa.org/#/dash) 5 [](https://melpa.org/#/dash) 6 7 # <img align="right" src="rainbow-dash.png"> dash.el 8 9 A modern list API for Emacs. No 10 [`'cl`](https://gnu.org/software/emacs/manual/html_node/cl/) required. 11 12 See the end of the file for license conditions. 13 14 ## Contents 15 16 * [Change log](#change-log) 17 * [Upcoming breaking change!](#upcoming-breaking-change) 18 * [Installation](#installation) 19 * [Functions](#functions) 20 * [Contribute](#contribute) 21 * [Contributors](#contributors) 22 * [License](#license) 23 24 ## Change log 25 26 See the [`NEWS.md`](NEWS.md) file. 27 28 ### Upcoming breaking change! 29 30 - For backward compatibility reasons, `-zip` when called with two 31 lists returns a list of cons cells, rather than a list of proper 32 lists. This is a clunky API, and may be changed in a future release 33 to always return a list of proper lists, as `-zip-lists` currently 34 does. 35 36 **N.B.:** Do not rely on the current behavior of `-zip` for two 37 lists. Instead, use `-zip-pair` for a list of cons cells, and 38 `-zip-lists` for a list of proper lists. 39 40 ## Installation 41 42 Dash is available on [GNU ELPA](https://elpa.gnu.org/), [GNU-devel 43 ELPA](https://elpa.gnu.org/devel/), and [MELPA](https://melpa.org/), 44 and can be installed with the standard command `package-install`: 45 46 M-x package-install RET dash RET 47 48 See [`(info "(emacs) Package 49 Installation")`](https://gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html). 50 51 Alternatively, you can just dump `dash.el` in your `load-path` 52 somewhere. See [`(info "(emacs) Lisp 53 Libraries")`](https://gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html). 54 55 ### Using in a package 56 57 Add something like this to the library's headers: 58 59 ;; Package-Requires: ((dash "[[ dash-version ]]")) 60 61 See [`(info "(elisp) Library 62 Headers")`](https://gnu.org/software/emacs/manual/html_node/elisp/Library-Headers.html). 63 64 ### Fontification of special variables 65 66 Font lock of special Dash variables (`it`, `acc`, etc.) in Emacs Lisp 67 buffers can optionally be enabled with the autoloaded minor mode 68 `dash-fontify-mode`. In older Emacs versions which do not dynamically 69 detect macros, the minor mode also fontifies Dash macro calls. 70 71 To automatically enable the minor mode in all Emacs Lisp buffers, just 72 call its autoloaded global counterpart `global-dash-fontify-mode`, 73 either interactively or from your `user-init-file`: 74 75 ```el 76 (global-dash-fontify-mode) 77 ``` 78 79 ### Info symbol lookup 80 81 While editing Elisp files, you can use `C-h S` (`info-lookup-symbol`) 82 to look up Elisp symbols in the relevant Info manuals (see [`(emacs) 83 Info 84 Lookup`](https://gnu.org/software/emacs/manual/html_node/emacs/Info-Lookup.html)). 85 To enable the same for Dash symbols, use the command 86 `dash-register-info-lookup`. It can be called directly when needed, 87 or automatically from your `user-init-file`. For example: 88 89 ```el 90 (with-eval-after-load 'info-look 91 (dash-register-info-lookup)) 92 ``` 93 94 ## Functions 95 96 All functions and constructs in the library use a dash (`-`) prefix. 97 98 The library also provides anaphoric macro versions of functions where 99 that makes sense. The names of these macros are prefixed with two 100 dashes (`--`) instead of one. 101 102 While `-map` applies a function to each element of a list, its 103 anaphoric counterpart `--map` evaluates a form with the local variable 104 `it` temporarily bound to the current list element instead. For 105 example: 106 107 ```el 108 (-map (lambda (n) (* n n)) '(1 2 3 4)) ; Normal version. 109 (--map (* it it) '(1 2 3 4)) ; Anaphoric version. 110 ``` 111 112 The normal version can of course also be written as follows: 113 114 ```el 115 (defun my-square (n) 116 "Return N multiplied by itself." 117 (* n n)) 118 119 (-map #'my-square '(1 2 3 4)) 120 ``` 121 122 This demonstrates the utility of both versions. 123 [[ function-list ]] 124 125 [[ function-docs ]] 126 ## Contribute 127 128 Yes, please do. Pure functions in the list manipulation realm only, 129 please. There's a suite of examples/tests in `dev/examples.el`, so 130 remember to add tests for your additions, or I might break them later. 131 132 You'll find the repo at: 133 134 https://github.com/magnars/dash.el 135 136 Run the tests with: 137 138 make check 139 140 Regenerate the docs with: 141 142 make docs 143 144 I highly recommend that you install these as a pre-commit hook, so 145 that the tests are always running and the docs are always in sync: 146 147 cp dev/pre-commit.sh .git/hooks/pre-commit 148 149 Oh, and don't edit `README.md` or `dash.texi` directly; they are 150 auto-generated. Change `readme-template.md` or `dash-template.texi` 151 instead, respectively. 152 153 To ensure that `dash.el` can be distributed with GNU ELPA or Emacs, we 154 require that all contributors assign copyright to the Free Software 155 Foundation. For more on this, see [`(info "(emacs) Copyright 156 Assignment")`](https://gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html). 157 158 ## Contributors 159 160 - [Matus Goljer](https://github.com/Fuco1) contributed lots of features and 161 functions. 162 - [Takafumi Arakaki](https://github.com/tkf) contributed `-group-by`. 163 - [tali713](https://github.com/tali713) is the author of `-applify`. 164 - [Víctor M. Valenzuela](https://github.com/vemv) contributed `-repeat`. 165 - [Nic Ferrier](https://github.com/nicferrier) contributed `-cons*`. 166 - [Wilfred Hughes](https://github.com/Wilfred) contributed `-slice`, 167 `-first-item`, and `-last-item`. 168 - [Emanuel Evans](https://github.com/shosti) contributed `-if-let`, `-when-let`, 169 and `-insert-at`. 170 - [Johan Andersson](https://github.com/rejeep) contributed `-sum`, `-product`, 171 and `-same-items?`. 172 - [Christina Whyte](https://github.com/kurisuwhyte) contributed `-compose`. 173 - [Steve Lamb](https://github.com/steventlamb) contributed `-cycle`, `-pad`, 174 `-annotate`, `-zip-fill`, and a variadic version of `-zip`. 175 - [Fredrik Bergroth](https://github.com/fbergroth) made the `-if-let` family use 176 `-let` destructuring and improved the script for generating documentation. 177 - [Mark Oteiza](https://github.com/holomorph) contributed `-iota` and 178 the script to create an Info manual. 179 - [Vasilij Schneidermann](https://github.com/wasamasa) contributed `-some`. 180 - [William West](https://github.com/occidens) made `-fixfn` more robust at 181 handling floats. 182 - [Cam Saul](https://github.com/camsaul) contributed `-some->`, `-some->>`, and 183 `-some-->`. 184 - [Basil L. Contovounesios](https://github.com/basil-conto) contributed 185 `-common-prefix`, `-common-suffix`, and various other improvements. 186 - [Paul Pogonyshev](https://github.com/doublep) contributed `-each-r` and 187 `-each-r-while`. 188 189 Thanks! 190 191 New contributors are very welcome. See the 192 [`Contribute`](#contribute) section above. 193 194 ## License 195 196 Copyright (C) 2012-2021 Free Software Foundation, Inc. 197 198 Author: Magnar Sveen <magnars@gmail.com> 199 200 This program is free software: you can redistribute it and/or modify 201 it under the terms of the GNU General Public License as published by 202 the Free Software Foundation, either version 3 of the License, or 203 (at your option) any later version. 204 205 This program is distributed in the hope that it will be useful, 206 but WITHOUT ANY WARRANTY; without even the implied warranty of 207 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 208 GNU General Public License for more details. 209 210 You should have received a copy of the GNU General Public License 211 along with this program. If not, see <https://www.gnu.org/licenses/>.