dash-template.texi (9042B)
1 \input texinfo @c -*- texinfo -*- 2 @c %**start of header 3 @setfilename dash.info 4 @set DASHVER @c [[ dash-version ]] 5 @settitle Dash: A modern list library for GNU Emacs. 6 @documentencoding UTF-8 7 @documentlanguage en 8 @c %**end of header 9 10 @copying 11 This manual is for Dash version @value{DASHVER}. 12 13 Copyright @copyright{} 2012--2021 Free Software Foundation, Inc. 14 15 @quotation 16 Permission is granted to copy, distribute and/or modify this document 17 under the terms of the GNU Free Documentation License, Version 1.3 or 18 any later version published by the Free Software Foundation; with the 19 Invariant Sections being ``GNU General Public License,'' and no 20 Front-Cover Texts or Back-Cover Texts. A copy of the license is 21 included in the section entitled ``GNU Free Documentation License''. 22 @end quotation 23 @end copying 24 25 @dircategory Emacs 26 @direntry 27 * Dash: (dash.info). A modern list library for GNU Emacs. 28 @end direntry 29 30 @titlepage 31 @title Dash Manual 32 @subtitle For Dash Version @value{DASHVER}. 33 @author Magnar Sveen 34 @page 35 @vskip 0pt plus 1filll 36 @insertcopying 37 @end titlepage 38 39 @contents 40 41 @ifnottex 42 @node Top 43 @top Dash 44 45 @insertcopying 46 @end ifnottex 47 48 @menu 49 * Installation:: Installing and configuring Dash. 50 * Functions:: Dash API reference. 51 * Development:: Contributing to Dash development. 52 53 Appendices 54 55 * FDL:: The license for this documentation. 56 * GPL:: Conditions for copying and changing Dash. 57 * Index:: Index including functions and macros. 58 59 @detailmenu 60 --- The Detailed Node Listing --- 61 62 Installation 63 64 * Using in a package:: Listing Dash as a package dependency. 65 * Fontification of special variables:: Font Lock of anaphoric macro variables. 66 * Info symbol lookup:: Looking up Dash symbols in this manual. 67 68 Functions 69 70 @c [[ function-list ]] 71 72 Development 73 74 * Contribute:: How to contribute. 75 * Contributors:: List of contributors. 76 @end detailmenu 77 @end menu 78 79 @node Installation 80 @chapter Installation 81 82 Dash is available on @url{https://elpa.gnu.org/, GNU ELPA}, 83 @url{https://elpa.gnu.org/devel/, GNU-devel ELPA}, and 84 @url{https://melpa.org/, MELPA}, and can be installed with the 85 standard command @code{package-install} (@pxref{Package 86 Installation,,, emacs, The GNU Emacs Manual}). 87 88 @table @kbd 89 @item M-x package-install @key{RET} dash @key{RET} 90 Install the Dash library. 91 @end table 92 93 Alternatively, you can just dump @file{dash.el} in your 94 @code{load-path} somewhere (@pxref{Lisp Libraries,,, emacs, The GNU 95 Emacs Manual}). 96 97 @menu 98 * Using in a package:: Listing Dash as a package dependency. 99 * Fontification of special variables:: Font Lock of anaphoric macro variables. 100 * Info symbol lookup:: Looking up Dash symbols in this manual. 101 @end menu 102 103 @node Using in a package 104 @section Using in a package 105 106 If you use Dash in your own package, be sure to list it as a 107 dependency in the library's headers as follows (@pxref{Library 108 Headers,,, elisp, The Emacs Lisp Reference Manual}). 109 110 @lisp 111 ;; Package-Requires: ((dash "@value{DASHVER}")) 112 @end lisp 113 114 @node Fontification of special variables 115 @section Fontification of special variables 116 117 @findex dash-fontify-mode 118 The autoloaded minor mode @code{dash-fontify-mode} is provided for 119 optional fontification of anaphoric Dash variables (@code{it}, 120 @code{acc}, etc.@:) in Emacs Lisp buffers using search-based Font Lock 121 (@pxref{Font Lock,,, emacs, The GNU Emacs Manual}). In older Emacs 122 versions which do not dynamically detect macros, the minor mode also 123 fontifies calls to Dash macros. 124 125 @findex global-dash-fontify-mode 126 To automatically enable the minor mode in all Emacs Lisp buffers, just 127 call its autoloaded global counterpart 128 @code{global-dash-fontify-mode}, either interactively or from your 129 @code{user-init-file}: 130 131 @lisp 132 (global-dash-fontify-mode) 133 @end lisp 134 135 @node Info symbol lookup 136 @section Info symbol lookup 137 138 @findex dash-register-info-lookup 139 While editing Elisp files, you can use @kbd{C-h S} 140 (@code{info-lookup-symbol}) to look up Elisp symbols in the relevant 141 Info manuals (@pxref{Info Lookup,,, emacs, The GNU Emacs Manual}). To 142 enable the same for Dash symbols, use the command 143 @code{dash-register-info-lookup}. It can be called directly when 144 needed, or automatically from your @code{user-init-file}. For 145 example: 146 147 @lisp 148 (with-eval-after-load 'info-look 149 (dash-register-info-lookup)) 150 @end lisp 151 152 @node Functions 153 @chapter Functions 154 155 This chapter contains reference documentation for the Dash 156 @acronym{API, Application Programming Interface}. The names of all 157 public functions defined in the library are prefixed with a dash 158 character (@samp{-}). 159 160 The library also provides anaphoric macro versions of functions where 161 that makes sense. The names of these macros are prefixed with two 162 dashes (@samp{--}) instead of one. 163 164 For instance, while the function @code{-map} applies a function to 165 each element of a list, its anaphoric counterpart @code{--map} 166 evaluates a form with the local variable @code{it} temporarily bound 167 to the current list element instead. 168 169 @lisp 170 @group 171 ;; Normal version. 172 (-map (lambda (n) (* n n)) '(1 2 3 4)) 173 @result{} (1 4 9 16) 174 @end group 175 176 @group 177 ;; Anaphoric version. 178 (--map (* it it) '(1 2 3 4)) 179 @result{} (1 4 9 16) 180 @end group 181 @end lisp 182 183 The normal version can, of course, also be written as in the following 184 example, which demonstrates the utility of both versions. 185 186 @lisp 187 @group 188 (defun my-square (n) 189 "Return N multiplied by itself." 190 (* n n)) 191 192 (-map #'my-square '(1 2 3 4)) 193 @result{} (1 4 9 16) 194 @end group 195 @end lisp 196 197 @menu 198 @c [[ function-list ]] 199 @end menu 200 201 @c [[ function-docs ]] 202 @node Development 203 @chapter Development 204 205 The Dash repository is hosted on GitHub at 206 @url{https://github.com/magnars/dash.el}. 207 208 @menu 209 * Contribute:: How to contribute. 210 * Contributors:: List of contributors. 211 @end menu 212 213 @node Contribute 214 @section Contribute 215 216 Yes, please do. Pure functions in the list manipulation realm only, 217 please. There's a suite of examples/tests in @file{dev/examples.el}, 218 so remember to add tests for your additions, or they may get broken 219 later. 220 221 Run the tests with @samp{make check}. Regenerate the docs with 222 @samp{make docs}. Contributors are encouraged to install these 223 commands as a Git pre-commit hook, so that the tests are always 224 running and the docs are always in sync: 225 226 @example 227 $ cp dev/pre-commit.sh .git/hooks/pre-commit 228 @end example 229 230 Oh, and don't edit @file{README.md} or @file{dash.texi} directly, as 231 they are auto-generated. Instead, change their respective templates 232 @file{readme-template.md} or @file{dash-template.texi}. 233 234 To ensure that Dash can be distributed with GNU ELPA or Emacs, we 235 require that all contributors assign copyright to the Free Software 236 Foundation. For more on this, @pxref{Copyright Assignment,,, emacs, 237 The GNU Emacs Manual}. 238 239 @node Contributors 240 @section Contributors 241 242 @itemize 243 @item 244 @url{https://github.com/Fuco1, Matus Goljer} contributed lots of 245 features and functions. 246 @item 247 @url{https://github.com/tkf, Takafumi Arakaki} contributed 248 @code{-group-by}. 249 @item 250 @url{https://github.com/tali713, tali713} is the author of 251 @code{-applify}. 252 @item 253 @url{https://github.com/vemv, V@'{i}ctor M. Valenzuela} contributed 254 @code{-repeat}. 255 @item 256 @url{https://github.com/nicferrier, Nic Ferrier} contributed 257 @code{-cons*}. 258 @item 259 @url{https://github.com/Wilfred, Wilfred Hughes} contributed 260 @code{-slice}, @code{-first-item}, and @code{-last-item}. 261 @item 262 @url{https://github.com/shosti, Emanuel Evans} contributed 263 @code{-if-let}, @code{-when-let}, and @code{-insert-at}. 264 @item 265 @url{https://github.com/rejeep, Johan Andersson} contributed 266 @code{-sum}, @code{-product}, and @code{-same-items?}. 267 @item 268 @url{https://github.com/kurisuwhyte, Christina Whyte} contributed 269 @code{-compose}. 270 @item 271 @url{https://github.com/steventlamb, Steve Lamb} contributed 272 @code{-cycle}, @code{-pad}, @code{-annotate}, @code{-zip-fill}, and a 273 variadic version of @code{-zip}. 274 @item 275 @url{https://github.com/fbergroth, Fredrik Bergroth} made the 276 @code{-if-let} family use @code{-let} destructuring and improved the 277 script for generating documentation. 278 @item 279 @url{https://github.com/holomorph, Mark Oteiza} contributed 280 @code{-iota} and the script to create an Info manual. 281 @item 282 @url{https://github.com/wasamasa, Vasilij Schneidermann} contributed 283 @code{-some}. 284 @item 285 @url{https://github.com/occidens, William West} made @code{-fixfn} 286 more robust at handling floats. 287 @item 288 @url{https://github.com/camsaul, Cam Saul} contributed @code{-some->}, 289 @code{-some->>}, and @code{-some-->}. 290 @item 291 @url{https://github.com/basil-conto, Basil L. Contovounesios} 292 contributed @code{-common-prefix}, @code{-common-suffix}, and various 293 other improvements. 294 @item 295 @url{https://github.com/doublep, Paul Pogonyshev} contributed 296 @code{-each-r} and @code{-each-r-while}. 297 @end itemize 298 299 Thanks! 300 301 New contributors are very welcome. @xref{Contribute}. 302 303 @c Appendices. 304 305 @node FDL 306 @appendix GNU Free Documentation License 307 @include doc/fdl.texi 308 309 @node GPL 310 @appendix GNU General Public License 311 @include doc/gpl.texi 312 313 @node Index 314 @unnumbered Index 315 @printindex fn 316 317 @bye