├── .elpaignore ├── Cask ├── rainbow-dash.png ├── dev ├── .nosearch ├── pre-commit.sh └── dash-defs.el ├── .gitignore ├── .dir-locals.el ├── .github └── workflows │ └── test.yml ├── dash-functional.el ├── Makefile ├── readme-template.md ├── dash-template.texi ├── NEWS.md ├── doc ├── fdl.texi └── gpl.texi └── LICENSE /.elpaignore: -------------------------------------------------------------------------------- 1 | dev/* 2 | -------------------------------------------------------------------------------- /Cask: -------------------------------------------------------------------------------- 1 | (package-file "dash.el") 2 | -------------------------------------------------------------------------------- /rainbow-dash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/magnars/dash.el/master/rainbow-dash.png -------------------------------------------------------------------------------- /dev/.nosearch: -------------------------------------------------------------------------------- 1 | This file excludes the current directory from load-path. 2 | See (info "(elisp) Library Search"). 3 | -------------------------------------------------------------------------------- /dev/pre-commit.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | git stash -q --keep-index 4 | make check 5 | RESULT=$? 6 | [ $RESULT -eq 0 ] && make docs && git add ./README.md 7 | git stash pop -q 8 | [ $RESULT -ne 0 ] && exit 1 9 | exit 0 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled Elisp 2 | *.elc 3 | 4 | # ELPA files. 5 | /dash-autoloads.el 6 | /dash-pkg.el 7 | 8 | # Personal customization. 9 | .dir-locals-2.el 10 | 11 | # ctags, etags. 12 | TAGS 13 | 14 | # Generated Info manual. 15 | dash.info 16 | -------------------------------------------------------------------------------- /.dir-locals.el: -------------------------------------------------------------------------------- 1 | ((nil 2 | (fill-column . 70) 3 | (sentence-end-double-space . t) 4 | (tab-width . 8)) 5 | (emacs-lisp-mode 6 | (indent-tabs-mode . nil) 7 | (mode . bug-reference-prog)) 8 | (sh-mode 9 | (sh-basic-offset . 4)) 10 | (texinfo-mode 11 | (indent-tabs-mode . nil) 12 | (mode . bug-reference-prog))) 13 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: [push, pull_request] 3 | permissions: {} 4 | jobs: 5 | build: 6 | runs-on: ubuntu-latest 7 | strategy: 8 | matrix: 9 | emacs_version: 10 | - '24.1' 11 | - '24.2' 12 | - '24.3' 13 | - '24.4' 14 | - '24.5' 15 | - '25.1' 16 | - '25.2' 17 | - '25.3' 18 | - '26.1' 19 | - '26.2' 20 | - '26.3' 21 | - '27.1' 22 | - '27.2' 23 | - '28.1' 24 | - '28.2' 25 | - '29.1' 26 | - '29.2' 27 | - '29.3' 28 | - '29.4' 29 | - '30.1' 30 | - '30.2' 31 | - 'release-snapshot' 32 | - 'snapshot' 33 | include: 34 | - emacs_version: 'snapshot' 35 | allow_failure: true 36 | steps: 37 | - uses: actions/checkout@v5 38 | with: 39 | persist-credentials: false 40 | - uses: purcell/setup-emacs@master 41 | with: 42 | version: ${{ matrix.emacs_version }} 43 | 44 | - name: Run tests 45 | if: matrix.allow_failure != true 46 | run: 'make check' 47 | 48 | - name: Run tests (allow failure) 49 | if: matrix.allow_failure == true 50 | run: 'make check || true' 51 | -------------------------------------------------------------------------------- /dash-functional.el: -------------------------------------------------------------------------------- 1 | ;;; dash-functional.el --- Collection of useful combinators for Emacs Lisp -*- lexical-binding: t -*- 2 | 3 | ;; Copyright (C) 2013-2021 Free Software Foundation, Inc. 4 | 5 | ;; Author: Matus Goljer 6 | ;; Magnar Sveen 7 | ;; Version: 1.3.0 8 | ;; Package-Requires: ((dash "2.18.0")) 9 | ;; Keywords: extensions, lisp 10 | ;; Homepage: https://github.com/magnars/dash.el 11 | 12 | ;; This program is free software: you can redistribute it and/or modify 13 | ;; it under the terms of the GNU General Public License as published by 14 | ;; the Free Software Foundation, either version 3 of the License, or 15 | ;; (at your option) any later version. 16 | 17 | ;; This program is distributed in the hope that it will be useful, 18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 | ;; GNU General Public License for more details. 21 | 22 | ;; You should have received a copy of the GNU General Public License 23 | ;; along with this program. If not, see . 24 | 25 | ;;; Commentary: 26 | 27 | ;; *N.B.:* This package has been absorbed, and is therefore made 28 | ;; obsolete, by the `dash' package, version 2.18.0. 29 | ;; 30 | ;; If you maintain a package that depends on `dash-functional', then 31 | ;; you should change that to instead depend on `dash' version 2.18.0, 32 | ;; and remove all references to `dash-functional'. 33 | ;; 34 | ;; If you use any packages that depend on `dash-functional', either 35 | ;; directly or indirectly, then you will have to wait until all of 36 | ;; them have transitioned away from it before you can remove it. 37 | ;; 38 | ;; For more information on this, see the following URL: 39 | ;; `https://github.com/magnars/dash.el/wiki/Obsoletion-of-dash-functional.el' 40 | 41 | ;;; Code: 42 | 43 | (require 'dash) 44 | 45 | (eval-and-compile 46 | (let ((msg "Package dash-functional is obsolete; use dash 2.18.0 instead")) 47 | (if (and noninteractive (fboundp 'byte-compile-warn)) 48 | (byte-compile-warn msg) 49 | (message "%s" msg)))) 50 | 51 | (provide 'dash-functional) 52 | 53 | ;;; dash-functional.el ends here 54 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Dash. 2 | 3 | # Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | # 5 | # This program is free software: you can redistribute it and/or modify 6 | # it under the terms of the GNU General Public License as published by 7 | # the Free Software Foundation, either version 3 of the License, or 8 | # (at your option) any later version. 9 | # 10 | # This program is distributed in the hope that it will be useful, 11 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 12 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 | # GNU General Public License for more details. 14 | # 15 | # You should have received a copy of the GNU General Public License 16 | # along with this program. If not, see . 17 | 18 | # Variables. 19 | 20 | EMACS ?= emacs 21 | batch := $(EMACS) -Q -batch -L . 22 | els := dash.el dev/dash-defs.el dev/examples.el 23 | elcs := $(addsuffix c,$(els)) 24 | docs := README.md dash.texi 25 | tmpls := readme-template.md dash-template.texi $(wildcard doc/*.texi) 26 | 27 | # Targets. 28 | 29 | lisp: $(elcs) 30 | .PHONY: lisp 31 | 32 | docs: $(docs) 33 | .PHONY: docs 34 | 35 | force-docs: maintainer-clean docs 36 | .PHONY: force-docs 37 | 38 | # ERT_SELECTOR is a Lisp expression determining which tests to run. 39 | # Its format is described in (info "(ert) Test Selectors"). It 40 | # defaults to selecting all tests. Note that in batch mode, a nil 41 | # selector is the same as t. 42 | check: ERT_SELECTOR ?= t 43 | check: run := '(ert-run-tests-batch-and-exit (quote $(ERT_SELECTOR)))' 44 | check: lisp 45 | EMACS_TEST_VERBOSE=1 $(batch) -l dev/examples -eval $(run) 46 | .PHONY: check 47 | 48 | all: lisp docs check 49 | .PHONY: all 50 | 51 | force-all: maintainer-clean lisp docs check 52 | .PHONY: force-all 53 | 54 | clean: 55 | $(RM) $(elcs) 56 | .PHONY: clean 57 | 58 | maintainer-clean: ver := 26 59 | maintainer-clean: msg := Doc regeneration requires $(ver)+ 60 | maintainer-clean: clean 61 | $(batch) -eval '(if (< emacs-major-version $(ver)) (error "$(msg)"))' 62 | $(RM) $(docs) 63 | .PHONY: maintainer-clean 64 | 65 | # Files. 66 | 67 | %.elc: WERROR := '(setq byte-compile-error-on-warn t)' 68 | %.elc: %.el 69 | $(batch) -eval $(WERROR) -f batch-byte-compile $< 70 | 71 | $(docs) &: $(elcs) $(tmpls) 72 | $(batch) -l dev/examples -f dash-make-docs 73 | 74 | dev/dash-defs.elc: dash.elc 75 | dev/examples.elc: dash.elc dev/dash-defs.elc 76 | -------------------------------------------------------------------------------- /readme-template.md: -------------------------------------------------------------------------------- 1 | [![CI](https://github.com/magnars/dash.el/actions/workflows/test.yml/badge.svg)](https://github.com/magnars/dash.el/actions/workflows/test.yml) 2 | [![GNU ELPA](https://elpa.gnu.org/packages/dash.svg)](https://elpa.gnu.org/packages/dash.html) 3 | [![GNU-devel ELPA](https://elpa.gnu.org/devel/dash.svg)](https://elpa.gnu.org/devel/dash.html) 4 | [![MELPA Stable](https://stable.melpa.org/packages/dash-badge.svg)](https://stable.melpa.org/#/dash) 5 | [![MELPA](https://melpa.org/packages/dash-badge.svg)](https://melpa.org/#/dash) 6 | 7 | # 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 | * [Installation](#installation) 18 | * [Functions](#functions) 19 | * [Contribute](#contribute) 20 | * [Contributors](#contributors) 21 | * [License](#license) 22 | 23 | ## Change log 24 | 25 | See the [`NEWS.md`](NEWS.md) file. 26 | 27 | ## Installation 28 | 29 | Dash is available on [GNU ELPA](https://elpa.gnu.org/), [GNU-devel 30 | ELPA](https://elpa.gnu.org/devel/), and [MELPA](https://melpa.org/), 31 | and can be installed with the standard command `package-install`: 32 | 33 | M-x package-install RET dash RET 34 | 35 | See [`(info "(emacs) Package 36 | Installation")`](https://gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html). 37 | 38 | Alternatively, you can just dump `dash.el` in your `load-path` 39 | somewhere. See [`(info "(emacs) Lisp 40 | Libraries")`](https://gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html). 41 | 42 | ### Using in a package 43 | 44 | Add something like this to the library's headers: 45 | 46 | ;; Package-Requires: ((dash "[[ dash-version ]]")) 47 | 48 | See [`(info "(elisp) Library 49 | Headers")`](https://gnu.org/software/emacs/manual/html_node/elisp/Library-Headers.html). 50 | 51 | ### Fontification of special variables 52 | 53 | Font lock of special Dash variables (`it`, `acc`, etc.) in Emacs Lisp 54 | buffers can optionally be enabled with the autoloaded minor mode 55 | `dash-fontify-mode`. In older Emacs versions which do not dynamically 56 | detect macros, the minor mode also fontifies Dash macro calls. 57 | 58 | To automatically enable the minor mode in all Emacs Lisp buffers, just 59 | call its autoloaded global counterpart `global-dash-fontify-mode`, 60 | either interactively or from your `user-init-file`: 61 | 62 | ```el 63 | (global-dash-fontify-mode) 64 | ``` 65 | 66 | ### Info symbol lookup 67 | 68 | While editing Elisp files, you can use `C-h S` (`info-lookup-symbol`) 69 | to look up Elisp symbols in the relevant Info manuals (see [`(emacs) 70 | Info 71 | Lookup`](https://gnu.org/software/emacs/manual/html_node/emacs/Info-Lookup.html)). 72 | To enable the same for Dash symbols, use the command 73 | `dash-register-info-lookup`. It can be called directly when needed, 74 | or automatically from your `user-init-file`. For example: 75 | 76 | ```el 77 | (with-eval-after-load 'info-look 78 | (dash-register-info-lookup)) 79 | ``` 80 | 81 | ## Functions 82 | 83 | All functions and constructs in the library use a dash (`-`) prefix. 84 | 85 | The library also provides anaphoric macro versions of functions where 86 | that makes sense. The names of these macros are prefixed with two 87 | dashes (`--`) instead of one. 88 | 89 | While `-map` applies a function to each element of a list, its 90 | anaphoric counterpart `--map` evaluates a form with the local variable 91 | `it` temporarily bound to the current list element instead. For 92 | example: 93 | 94 | ```el 95 | (-map (lambda (n) (* n n)) '(1 2 3 4)) ; Normal version. 96 | (--map (* it it) '(1 2 3 4)) ; Anaphoric version. 97 | ``` 98 | 99 | The normal version can of course also be written as follows: 100 | 101 | ```el 102 | (defun my-square (n) 103 | "Return N multiplied by itself." 104 | (* n n)) 105 | 106 | (-map #'my-square '(1 2 3 4)) 107 | ``` 108 | 109 | This demonstrates the utility of both versions. 110 | [[ function-list ]] 111 | 112 | [[ function-docs ]] 113 | ## Contribute 114 | 115 | Yes, please do. Pure functions in the list manipulation realm only, 116 | please. There's a suite of examples/tests in `dev/examples.el`, so 117 | remember to add tests for your additions, or I might break them later. 118 | 119 | You'll find the repo at: 120 | 121 | https://github.com/magnars/dash.el 122 | 123 | Run the tests with: 124 | 125 | make check 126 | 127 | Regenerate the docs with: 128 | 129 | make docs 130 | 131 | I highly recommend that you install these as a pre-commit hook, so 132 | that the tests are always running and the docs are always in sync: 133 | 134 | cp dev/pre-commit.sh .git/hooks/pre-commit 135 | 136 | Oh, and don't edit `README.md` or `dash.texi` directly; they are 137 | auto-generated. Change `readme-template.md` or `dash-template.texi` 138 | instead, respectively. 139 | 140 | To ensure that `dash.el` can be distributed with GNU ELPA or Emacs, we 141 | require that all contributors assign copyright to the Free Software 142 | Foundation. For more on this, see [`(info "(emacs) Copyright 143 | Assignment")`](https://gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html). 144 | 145 | ## Contributors 146 | 147 | - [Matus Goljer](https://github.com/Fuco1) contributed lots of features and 148 | functions. 149 | - [Takafumi Arakaki](https://github.com/tkf) contributed `-group-by`. 150 | - [tali713](https://github.com/tali713) is the author of `-applify`. 151 | - [Víctor M. Valenzuela](https://github.com/vemv) contributed `-repeat`. 152 | - [Nic Ferrier](https://github.com/nicferrier) contributed `-cons*`. 153 | - [Wilfred Hughes](https://github.com/Wilfred) contributed `-slice`, 154 | `-first-item`, and `-last-item`. 155 | - [Emanuel Evans](https://github.com/shosti) contributed `-if-let`, `-when-let`, 156 | and `-insert-at`. 157 | - [Johan Andersson](https://github.com/rejeep) contributed `-sum`, `-product`, 158 | and `-same-items?`. 159 | - [Christina Whyte](https://github.com/kurisuwhyte) contributed `-compose`. 160 | - [Steve Lamb](https://github.com/steventlamb) contributed `-cycle`, `-pad`, 161 | `-annotate`, `-zip-fill`, and a variadic version of `-zip`. 162 | - [Fredrik Bergroth](https://github.com/fbergroth) made the `-if-let` family use 163 | `-let` destructuring and improved the script for generating documentation. 164 | - [Mark Oteiza](https://github.com/holomorph) contributed `-iota` and 165 | the script to create an Info manual. 166 | - [Vasilij Schneidermann](https://github.com/wasamasa) contributed `-some`. 167 | - [William West](https://github.com/occidens) made `-fixfn` more robust at 168 | handling floats. 169 | - [Cam Saul](https://github.com/camsaul) contributed `-some->`, `-some->>`, and 170 | `-some-->`. 171 | - [Basil L. Contovounesios](https://github.com/basil-conto) contributed 172 | `-common-prefix`, `-common-suffix`, and various other improvements. 173 | - [Paul Pogonyshev](https://github.com/doublep) contributed `-each-r` and 174 | `-each-r-while`. 175 | 176 | Thanks! 177 | 178 | New contributors are very welcome. See the 179 | [`Contribute`](#contribute) section above. 180 | 181 | ## License 182 | 183 | Copyright (C) 2012-2025 Free Software Foundation, Inc. 184 | 185 | Author: Magnar Sveen 186 | 187 | This program is free software: you can redistribute it and/or modify 188 | it under the terms of the GNU General Public License as published by 189 | the Free Software Foundation, either version 3 of the License, or 190 | (at your option) any later version. 191 | 192 | This program is distributed in the hope that it will be useful, 193 | but WITHOUT ANY WARRANTY; without even the implied warranty of 194 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 195 | GNU General Public License for more details. 196 | 197 | You should have received a copy of the GNU General Public License 198 | along with this program. If not, see . 199 | -------------------------------------------------------------------------------- /dash-template.texi: -------------------------------------------------------------------------------- 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--2025 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 318 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # Dash NEWS -- history of user-visible changes 2 | 3 | Copyright (C) 2012-2025 Free Software Foundation, Inc. 4 | 5 | See the end of the file for license conditions. 6 | 7 | ## Change log 8 | 9 | ### From 2.19.1 to 2.20.0 10 | 11 | #### Deprecations 12 | 13 | - Calling `-zip` with two arguments now emits a warning. This 14 | long-discouraged calling convention remains supported, but the 15 | caller is now referred to the equivalent `-zip-pair` instead (Stefan 16 | Monnier, #400). 17 | - Calling `-zip-pair` with less than or more than two arguments is now 18 | deprecated, and can be replaced with the equivalent call to 19 | `-zip-lists` instead. 20 | 21 | #### Fixes 22 | 23 | - Fixed a regression from `2.18` in `-take` that caused it to 24 | prematurely signal an error on improper lists (#393). 25 | - The function `-pad` can now be called with zero lists as arguments. 26 | - The functions `-union`, `-intersection`, and `-difference` now 27 | return proper sets, without duplicate elements (#397). 28 | - The functions `-same-items?` and `-permutations` now work on 29 | multisets (lists with duplicate elements) (#390, #397, #399). 30 | 31 | For example: 32 | 33 | ```el 34 | (-same-items? '(1 1 2 3) '(3 1 2)) ; => t 35 | (-permutations '(1 1 2)) ; => '((1 1 2) (1 2 1) (2 1 1)) 36 | ``` 37 | 38 | - Several functions which are documented as returning a fresh, mutable 39 | object (such as a copy of one of their arguments) are no longer 40 | marked as `pure`. Pure functions called with constant arguments are 41 | evaluated during byte-compilation; the resulting value is an 42 | immutable constant, and thus unsafe to modify destructively. The 43 | functions in question are: `-clone`, `-cons*`, `-drop-last`, 44 | `-interleave`, `-interpose`, `-iota`, `-non-nil`, `-repeat`, 45 | `-slice`, `-snoc`, `-split-at`, `-take`, `-take-last`. 46 | 47 | #### New features 48 | 49 | - The function `-contains?` now returns the matching tail of the list 50 | instead of just `t`, similarly to `member` (#397). 51 | - New function `-frequencies` that takes a list and counts how many 52 | times each distinct element occurs in it (suggested by @ebpa, #209, 53 | #214, #399). 54 | - New functions `-zip-lists-fill` and `-unzip-lists` which are 55 | better-behaved versions of `-zip-fill` and `-unzip`, respectively 56 | (#400). 57 | 58 | ### From 2.19.0 to 2.19.1 59 | 60 | #### Fixes 61 | 62 | - Fixed a regression from `2.18` in `-is-suffix-p` which led to false 63 | negatives when parts of the suffix appeared multiple times in the 64 | list being searched (Bennett Rennier, #384). 65 | 66 | ### From 2.18.1 to 2.19.0 67 | 68 | #### Fixes 69 | 70 | - Reverted a breaking change introduced in `2.18.0` that caused the 71 | threading macro `-->` to be indented differently from `->` and `->>` 72 | (#375). 73 | - Added and fixed Edebug specifications for many Dash macros (Philipp 74 | Stephani, #380, #381). 75 | 76 | #### New features 77 | 78 | - The combinators `-on`, `-flip`, `-not`, `-andfn`, and `-orfn` now 79 | return variadic functions that take any number of arguments (#308). 80 | - New combinator `-rotate-args` similar to `-flip`, but for arbitrary 81 | arglist rotations (suggested by @vapniks, #72). 82 | - New function `-every` and its anaphoric macro counterpart `--every`. 83 | They are like the existing `-every-p` and `--every-p`, respectively, 84 | but return the last non-`nil` result instead of just `t`. 85 | - New macro `--partition-after-pred` which affords 86 | `-partition-after-pred` better performance (Per Weijnitz, #362). 87 | 88 | ### From 2.18.0 to 2.18.1 89 | 90 | - Fixed a regression from `2.17` as well as a long-standing bug in 91 | `--iterate`, which evaluated its arguments one too many times. This 92 | in turn could lead to errors in `-flatten-n` when it tried 93 | flattening certain structures too far (#373). 94 | 95 | ### From 2.17 to 2.18 96 | 97 | This release absorbs the now obsolete `dash-functional` version 98 | `1.3.0` into `dash`, and brings the very old version of `dash` on GNU 99 | ELPA up to date. 100 | 101 | Package maintainers should replace all uses of `dash-functional`, 102 | which will eventually be deleted, with `dash` version `2.18.0`. For 103 | more information on this, see: 104 | https://github.com/magnars/dash.el/wiki/Obsoletion-of-dash-functional.el 105 | 106 | - New function `-iota` for generating arithmetic sequences 107 | (@holomorph, #215). 108 | 109 | - Calling `-list` with more than one argument is now deprecated. 110 | 111 | - `-lambda` now accepts an empty argument list. 112 | 113 | - New anaphoric macros `--reductions-from`, `--reductions`, 114 | `--reductions-r-from`, and `--reductions-r` corresponding to the 115 | analogous non-anaphoric functions. 116 | 117 | - `-doto` threading now works as with `->`. 118 | 119 | - New buffer-local minor mode `dash-fontify-mode` and globalized 120 | counterpart `global-dash-fontify-mode` for fontifying special Dash 121 | variables such as `it`, `it-index`, `acc`, etc. The minor mode also 122 | fontifies calls to Dash macros in older Emacs versions which did not 123 | dynamically detect macro calls. 124 | 125 | This obsoletes the user option `dash-enable-fontlock` and the 126 | function `dash-enable-font-lock`, which is now an alias of 127 | `global-dash-fontify-mode`. 128 | 129 | - New command `dash-register-info-lookup` for integration with `C-h S` 130 | (`info-lookup-symbol`). This command allows Dash symbols to be 131 | looked up in the Dash manual just like Elisp symbols are looked up 132 | in the Elisp manual. The command can be called directly when 133 | needed, or automatically from your `user-init-file`. For example: 134 | 135 | ```el 136 | (with-eval-after-load 'info-look 137 | (dash-register-info-lookup)) 138 | ``` 139 | 140 | - Dash is now listed under the standard [Customization 141 | groups](https://gnu.org/software/emacs/manual/html_node/emacs/Customization-Groups.html) 142 | and [Finder 143 | keywords](https://gnu.org/software/emacs/manual/html_node/emacs/Package-Keywords.html) 144 | `extensions` and `lisp`. 145 | 146 | - The Dash manual is now licensed under the GNU Free Documentation 147 | License version 1.3. 148 | 149 | - Various other bug fix, performance, byte-compilation, and 150 | documentation improvements. 151 | 152 | ### From 2.16 to 2.17 153 | 154 | - Sped up `-uniq` by using hash-tables when possible (@cireu, #305). 155 | - Fixed `-inits` to be non-destructive (@SwiftLawnGnome, #313). 156 | - Fixed indent rules for `-some->` and family (@wbolster, #321). 157 | - Added `-zip-lists` which always returns a list of proper lists, even 158 | for two input lists, in contrast to `-zip` (see issue #135). 159 | 160 | ### From 2.15 to 2.16 161 | 162 | - Added `--doto`, anaphoric version of `-doto` (#282). 163 | - Aliased `-cons-pair-p` to `-cons-pair?` (#288). 164 | - Generalized `-rotate` for `|N|` greater than the length of the list (@leungbk, 165 | #290). 166 | - Added a mechanism to extend destructuring with custom matchers (@yyoncho, 167 | #277). 168 | 169 | ### From 2.14 to 2.15 170 | 171 | This release brings new destructuring features, some new control flow 172 | functions and performance optimizations. 173 | 174 | - Added `-setq` with destructuring binding support similar to the `-let` family 175 | (#116). 176 | - Added smarter key destructuring in `-let` and friends where variables are 177 | auto-derived from keys (#111). 178 | - Allowed `-let` bindings without a source value form (#256). 179 | - Added `-each-r` and `-each-r-while` (@doublep, #159). 180 | - Added `-common-suffix` (@basil-conto, #263). 181 | - Improved performance of folds (`-reduce` and friends) (@basil-conto, #264). 182 | 183 | ### From 2.13 to 2.14 184 | 185 | This release retired Emacs 23 support. 186 | 187 | - Added Edebug support for threading macros (@Wilfred). 188 | - Added `-unzip`. 189 | - Added support for `-first-item` and `-last-item` as [place 190 | forms](https://gnu.org/software/emacs/manual/html_node/elisp/Generalized-Variables.html). 191 | - Added `-powerset` and `-permutations` (@holomorph). 192 | - Added `-as->` for threading a named variable (@zck). 193 | - Added `-partition-after-pred`, `-partition-before-pred`, 194 | `-partition-after-item`, and `-partition-before-item` (@zck). 195 | - Fixed a bug in `-any-p` and friends testing for `null` on lists containing 196 | `nil` (#239). 197 | - Fixed infinite loop bug in `-zip` and `-interleave` when called with empty 198 | input. 199 | - Added `-second-item` through `-fifth-item` as alternatives to `nth` 200 | (@Wilfred). 201 | - Added `-tails` and `-inits`. 202 | - Added `-running-sum` and `-running-product`. 203 | - Added the `-reductions[-r][-from]` family of functions (like `-reduce` but 204 | collecting intermediate results). 205 | - Added `-common-prefix` (@basil-conto). 206 | 207 | ### From 2.12 to 2.13 208 | 209 | - `-let` now supports `&alist` destructuring. 210 | - Various performance improvements. 211 | - `-zip` might change in a future release to always return a list of proper 212 | lists. Added `-zip-pair` for users who explicitly want the old behavior. 213 | - Enabled lexical binding in `dash.el` for Emacs versions 24 or newer (#130). 214 | - Added `-select-column` and `-select-columns`. 215 | - Fixed `-map-last` and `--remove-last` to be non-destructive (#158). 216 | - Added `-each-indexed` and `--each-indexed`. 217 | - Added `-take-last` and `-drop-last`. 218 | - Added the `-doto` macro. 219 | - `-cut <>` is now treated as a function, consistent with [SRFI 220 | 26](https://srfi.schemers.org/srfi-26/srfi-26.html) (#185). 221 | 222 | ### From 2.11 to 2.12 223 | 224 | - Added GNU ELPA support (Phillip Lord). 225 | - Added `-some->`, `-some->>`, and `-some-->` macros (Cam Saul). 226 | - `-is-suffix?` is now non-destructive. 227 | - Faster hash table implementation for `-union`. 228 | - Improvements to docstrings and examples. 229 | 230 | ### From 2.10 to 2.11 231 | 232 | - Lots of clean up w.r.t. byte compilation, debug macros, and tests. 233 | 234 | ### From 2.9 to 2.10 235 | 236 | - Added `-let` destructuring to `-if-let` and `-when-let` (Fredrik Bergroth). 237 | 238 | ### From 2.8 to 2.9 239 | 240 | - Added `-let`, `-let*`, and `-lambda` with destructuring. 241 | - Added `-tree-seq` and `-tree-map-nodes`. 242 | - Added `-non-nil`. 243 | - Added `-fix`. 244 | - Added `-fixfn` (`dash-functional` version `1.2`). 245 | - Added `-copy` (Wilfred Hughes). 246 | 247 | ### From 2.7 to 2.8 248 | 249 | - Added `-butlast`. 250 | 251 | ### From 2.6 to 2.7 252 | 253 | - `-zip` now supports more than two lists (Steve Lamb). 254 | - Added `-cycle`, `-pad`, `-annotate`, and `-zip-fill` (Steve Lamb). 255 | - Added `-table`, `-table-flat` (finite Cartesian product). 256 | - Added `-flatten-n`. 257 | - `-slice` now supports a "step" argument. 258 | - Added functional combinators `-iteratefn` and `-prodfn`. 259 | - Added `-replace`, `-splice`, and `-splice-list` which generalize `-replace-at` 260 | and `-insert-at`. 261 | - Added `-compose`, `-iteratefn`, and `-prodfn` (`dash-functional` version 262 | `1.1`). 263 | 264 | ### From 2.5 to 2.6 265 | 266 | - Added `-is-prefix-p`, `-is-suffix-p`, and `-is-infix-p` (Matus Goljer). 267 | - Added `-iterate` and `-unfold` (Matus Goljer). 268 | - Added `-split-on` and `-split-when` (Matus Goljer). 269 | - Added `-find-last-index` (Matus Goljer). 270 | - Added `-list` (Johan Andersson). 271 | 272 | ### From 2.4 to 2.5 273 | 274 | - Added `-same-items?` (Johan Andersson). 275 | - Various bugfixes. 276 | 277 | ### From 2.3 to 2.4 278 | 279 | - Added `-snoc` (Matus Goljer). 280 | - Added `-replace-at`, `-update-at`, `-remove-at`, and `-remove-at-indices` 281 | (Matus Goljer). 282 | 283 | ### From 2.2 to 2.3 284 | 285 | - Added tree operations (Matus Goljer). 286 | - Made Font Lock optional. 287 | 288 | ### From 2.1 to 2.2 289 | 290 | - Added `-compose` (Christina Whyte). 291 | 292 | ### From 2.0 to 2.1 293 | 294 | - Added indexing operations (Matus Goljer). 295 | 296 | ### From 1.8 to 2.0 297 | 298 | - Split out `dash-functional.el` (Matus Goljer). 299 | - Added `-andfn`, `-orfn`, `-not`, `-cut`, `-const`, `-flip`, and `-on` (Matus 300 | Goljer). 301 | - Fixed `-min`, `-max`, `-min-by`, and `-max-by` (Matus Goljer). 302 | 303 | ### From 1.7 to 1.8 304 | 305 | - Added `-first-item` and `-last-item` (Wilfred Hughes). 306 | 307 | ### From 1.6 to 1.7 308 | 309 | - Added `-rotate` (Matus Goljer). 310 | 311 | ### From 1.5 to 1.6 312 | 313 | - Added `-min`, `-max`, `-min-by`, and `-max-by` (Johan Andersson). 314 | 315 | ### From 1.4 to 1.5 316 | 317 | - Added `-sum` and `-product` (Johan Andersson). 318 | 319 | ### From 1.3 to 1.4 320 | 321 | - Added `-sort`. 322 | - Added `-reduce-r` (Matus Goljer). 323 | - Added `-reduce-r-from` (Matus Goljer). 324 | 325 | ### From 1.2 to 1.3 326 | 327 | - Added `-partition-in-steps`. 328 | - Added `-partition-all-in-steps`. 329 | 330 | ### From 1.1 to 1.2 331 | 332 | - Added `-last` (Matus Goljer). 333 | - Added `-insert-at` (Emanuel Evans). 334 | - Added `-when-let` and `-if-let` (Emanuel Evans). 335 | - Added `-when-let*` and `-if-let*` (Emanuel Evans). 336 | - Various bugfixes. 337 | 338 | ## License 339 | 340 | This program is free software: you can redistribute it and/or modify 341 | it under the terms of the GNU General Public License as published by 342 | the Free Software Foundation, either version 3 of the License, or 343 | (at your option) any later version. 344 | 345 | This program is distributed in the hope that it will be useful, 346 | but WITHOUT ANY WARRANTY; without even the implied warranty of 347 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 348 | GNU General Public License for more details. 349 | 350 | You should have received a copy of the GNU General Public License 351 | along with this program. If not, see . 352 | -------------------------------------------------------------------------------- /dev/dash-defs.el: -------------------------------------------------------------------------------- 1 | ;;; dash-defs.el --- Definitions for Dash examples -*- lexical-binding: t -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; This program is free software: you can redistribute it and/or modify 6 | ;; it under the terms of the GNU General Public License as published by 7 | ;; the Free Software Foundation, either version 3 of the License, or 8 | ;; (at your option) any later version. 9 | 10 | ;; This program is distributed in the hope that it will be useful, 11 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 12 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 | ;; GNU General Public License for more details. 14 | 15 | ;; You should have received a copy of the GNU General Public License 16 | ;; along with this program. If not, see . 17 | 18 | ;;; Code: 19 | 20 | (require 'dash) 21 | (require 'ert) 22 | (require 'find-func) 23 | ;; Added in Emacs 24.4; wrap in `eval-when-compile' when support is dropped. 24 | (require 'subr-x nil t) 25 | (declare-function string-remove-prefix "subr-x" (prefix string)) 26 | (declare-function string-remove-suffix "subr-x" (suffix string)) 27 | 28 | (defvar dash--groups () 29 | "Alist of grouped examples. 30 | 31 | Each element is of the form (NAME . DOC) or (FN . EXAMPLES) 32 | corresponding to the eponymous arguments of `def-example-group' 33 | and `defexamples', respectively. The only difference is that 34 | EXAMPLES are partitioned into triples (ACTUAL OP EXPECTED), where 35 | EXPECTED should be the result of evaluating ACTUAL, and OP is one 36 | of the following comparison operators: 37 | 38 | - `=>' ACTUAL should be `equal' to EXPECTED. 39 | - `~>' ACTUAL should be `approx=' to EXPECTED. 40 | - `!!>' ACTUAL should signal the EXPECTED error, 41 | either an error symbol or an error object.") 42 | 43 | (defvar dash--epsilon 1e-15 44 | "Epsilon used in `approx='.") 45 | 46 | (defun approx= (u v) 47 | "Like `=', but compares floats within `dash--epsilon'. 48 | This allows approximate comparison of floats to work around 49 | differences in implementation between systems. Used in place of 50 | `equal' when testing actual and expected values with `~>'." 51 | (or (= u v) 52 | (< (/ (abs (- u v)) 53 | (max (abs u) (abs v))) 54 | dash--epsilon))) 55 | 56 | (defun dash--example-to-test (example) 57 | "Return an ERT assertion form based on EXAMPLE. 58 | Signal an error if EXAMPLE is malformed." 59 | (pcase example 60 | (`(,actual => ,expected) `(should (equal ,actual ,expected))) 61 | (`(,actual ~> ,expected) `(should (approx= ,actual ,expected))) 62 | (`(,actual !!> ,(and (pred symbolp) expected)) 63 | `(should-error ,actual :type ',expected)) 64 | (`(,actual !!> ,expected) 65 | `(should (equal (should-error ,actual) ',expected))) 66 | (_ (error "Invalid test case: %S" example)))) 67 | 68 | (defmacro def-example-group (name doc &rest examples) 69 | "Define a group with NAME and DOC of EXAMPLES of several functions. 70 | See `dash--groups'." 71 | (declare (indent defun)) 72 | `(progn 73 | (push (cons ,name ,doc) dash--groups) 74 | ,@examples)) 75 | 76 | (defvar dash--find-example-regexp 77 | ;; Could use `rx' directly in Emacs 27+ 78 | ;; (or not rely on `find-function-space-re'). 79 | (let ((re `(: "(defexamples" (regexp ,find-function-space-re) 80 | symbol-start (regexp "%s") symbol-end))) 81 | (rx-to-string re t)) 82 | "Regexp matching `defexamples' for `find-function-regexp-alist'.") 83 | 84 | (defmacro defexamples (fn &rest examples) 85 | "Define a set of EXAMPLES and corresponding ERT tests for FN. 86 | See `dash--groups'." 87 | (declare (indent defun)) 88 | (let (triples tests) 89 | (while (let ((triple (-take 3 examples))) 90 | (push (dash--example-to-test triple) tests) 91 | (push triple triples) 92 | (setq examples (nthcdr 3 examples)))) 93 | `(progn 94 | (push (cons ',fn ',(nreverse triples)) dash--groups) 95 | (when (fboundp 'find-function-update-type-alist) 96 | ;; Help `ert-describe-test' locate examples in Emacs 31+. 97 | (find-function-update-type-alist 98 | ',fn 'ert--test 'dash--find-example-regexp)) 99 | (ert-deftest ,fn () ,@(nreverse tests))))) 100 | 101 | ;; Added in Emacs 25.1. 102 | (defvar text-quoting-style) 103 | 104 | (autoload 'help-fns--analyze-function "help-fns") 105 | 106 | (defun dash--describe (fn) 107 | "Return the (ARGLIST . DOCSTRING) of FN symbol. 108 | Based on `describe-function-1'." 109 | ;; Gained last arg in Emacs 25.1. 110 | (declare-function help-fns--signature "help-fns" 111 | (function doc real-def real-function buffer)) 112 | (or (get fn 'dash-doc) 113 | (with-temp-buffer 114 | (pcase-let* ((text-quoting-style 'grave) 115 | (`(,real-fn ,_def ,_alias ,real-def) 116 | (help-fns--analyze-function fn)) 117 | (buf (current-buffer)) 118 | (doc-raw (documentation fn t)) 119 | (doc (help-fns--signature 120 | fn doc-raw real-def real-fn buf))) 121 | (goto-char (1+ (point-min))) 122 | (delete-region (point) (progn (forward-sexp) (1+ (point)))) 123 | (downcase-region (point) (point-max)) 124 | (backward-char) 125 | ;; Memoize. 126 | (put fn 'dash-doc (cons (read buf) doc)))))) 127 | 128 | (defun dash--replace-all (old new) 129 | "Replace occurrences of OLD with NEW in current buffer." 130 | (goto-char (point-min)) 131 | (while (search-forward old nil t) 132 | (replace-match new t t))) 133 | 134 | (defun dash--github-link (fn) 135 | "Return a GitHub Flavored Markdown link to FN." 136 | (or (get fn 'dash-link) 137 | (let* ((sig (car (dash--describe fn))) 138 | (id (string-remove-prefix "!" (format "%s%s" fn sig))) 139 | (id (replace-regexp-in-string (rx (+ (not (in alnum ?-)))) 140 | "-" id t t)) 141 | (id (string-remove-suffix "-" id))) 142 | ;; Memoize. 143 | (put fn 'dash-link (format "[`%s`](#%s)" fn id))))) 144 | 145 | (defun dash--argnames-to-md () 146 | "Downcase and quote arg names in current buffer for Markdown." 147 | (let ((beg (point-min))) 148 | (while (setq beg (text-property-any beg (point-max) 149 | 'face 'help-argument-name)) 150 | (goto-char beg) 151 | (insert ?`) 152 | (goto-char (or (next-single-property-change (point) 'face) 153 | (point-max))) 154 | (downcase-region (1+ beg) (point)) 155 | (insert ?`) 156 | (setq beg (point))))) 157 | 158 | (defun dash--metavars-to-md () 159 | "Downcase and quote metavariables in current buffer for Markdown." 160 | (goto-char (point-min)) 161 | (while (re-search-forward (rx bow (group (in upper) (* (in upper ?-)) (* num)) 162 | (| (group ?\() (: (group (? "th")) eow))) 163 | nil t) 164 | (unless (match-beginning 2) 165 | (let* ((suf (match-string 3)) 166 | (var (format "`%s`%s" (downcase (match-string 1)) suf))) 167 | (replace-match var t t))))) 168 | 169 | (defun dash--hyperlinks-to-md () 170 | "Convert hyperlinks in current buffer from Elisp to Markdown." 171 | (goto-char (point-min)) 172 | (while (re-search-forward (rx ?` (+? (not (in " `"))) ?\') nil t) 173 | (let ((fn (intern (substring (match-string 0) 1 -1)))) 174 | (replace-match (if (assq fn dash--groups) 175 | (save-match-data (dash--github-link fn)) 176 | (format "`%s`" fn)) 177 | t t)))) 178 | 179 | (defun dash--booleans-to-md () 180 | "Mark up booleans (nil/t) in current buffer as Markdown." 181 | (goto-char (point-min)) 182 | (while (re-search-forward (rx bow (| "nil" "t") eow) nil t) 183 | (unless (memql (char-before (match-beginning 0)) '(?\' ?`)) 184 | (replace-match "`\\&`" t)))) 185 | 186 | (defun dash--indent-md-blocks () 187 | "Indent example blocks in current buffer for Markdown." 188 | (goto-char (point-min)) 189 | (while (re-search-forward (rx bol " ") nil t) 190 | (replace-match " " t t))) 191 | 192 | (defun dash--docstring-to-md (doc) 193 | "Transcribe DOC to Markdown syntax." 194 | (with-temp-buffer 195 | (insert doc) 196 | (dash--argnames-to-md) 197 | (dash--metavars-to-md) 198 | (dash--hyperlinks-to-md) 199 | (dash--booleans-to-md) 200 | (dash--indent-md-blocks) 201 | (buffer-string))) 202 | 203 | (defun dash--docstring-to-texi (doc) 204 | "Transcribe DOC to Texinfo syntax." 205 | (with-temp-buffer 206 | (insert doc) 207 | ;; Escape literal ?@. 208 | (dash--replace-all "@" "@@") 209 | (goto-char (point-min)) 210 | ;; TODO: Use `help-argument-name' like in `dash--argnames-to-md'? 211 | (while (re-search-forward 212 | (rx (| (group bow (in "A-Z") (* (in "A-Z" ?-)) (* num) eow) 213 | (: ?` (group (+? (not (in ?\s)))) ?\') 214 | (group bow (| "nil" "t") eow) 215 | (: "..." (? (group eol))))) 216 | nil t) 217 | (cond ((match-beginning 1) 218 | ;; Downcase metavariable reference. 219 | (downcase-region (match-beginning 1) (match-end 1)) 220 | (replace-match "@var{\\1}" t)) 221 | ((match-beginning 2) 222 | ;; `quoted' symbol. 223 | (replace-match (if (assq (intern (match-string 2)) dash--groups) 224 | "@code{\\2} (@pxref{\\2})" 225 | "@code{\\2}") 226 | t)) 227 | ;; nil/t. 228 | ((match-beginning 3) 229 | (unless (= (char-before (match-beginning 3)) ?\') 230 | (replace-match "@code{\\3}" t))) 231 | ;; Ellipses. 232 | ((match-beginning 4) (replace-match "@enddots{}" t t)) 233 | ((replace-match "@dots{}" t t)))) 234 | (buffer-string))) 235 | 236 | ;; Added in Emacs 26.1. 237 | (defvar print-escape-control-characters) 238 | 239 | (defun dash--lisp-to-md (obj) 240 | "Print Lisp OBJ suitably for Markdown." 241 | (let ((print-quoted t) 242 | (print-escape-control-characters t)) 243 | (save-excursion (prin1 obj))) 244 | (while (re-search-forward (rx (| (group ?\' symbol-start "nil" symbol-end) 245 | (group "\\00") "\\?")) 246 | nil 'move) 247 | (replace-match (cond ((match-beginning 1) "()") ; 'nil -> (). 248 | ((match-beginning 2) "\\") ; \00N -> \N. 249 | ("?")) ; `-any\?' -> `-any?'. 250 | t t))) 251 | 252 | (defun dash--lisp-to-texi (obj) 253 | "Print Lisp OBJ suitably for Texinfo." 254 | (save-excursion (dash--lisp-to-md obj)) 255 | (while (re-search-forward (rx (in "{}")) nil 'move) 256 | (replace-match "@\\&" t))) ;; { -> @{. 257 | 258 | (defun dash--expected (obj err) 259 | "Prepare OBJ for printing as an expected evaluation result. 260 | ERR non-nil means OBJ is either an error symbol or error object." 261 | (cond ((and (eq (car-safe obj) 'quote) 262 | (not (equal obj ''()))) 263 | ;; Unquote expected result. 264 | (cadr obj)) 265 | ;; Print actual error message. 266 | (err (error-message-string (-list obj))) 267 | (obj))) 268 | 269 | (defun dash--example-to-md (example) 270 | "Return a Markdown string documenting EXAMPLE." 271 | (pcase-let* ((`(,actual ,op ,expected) example) 272 | (err (eq op '!!>))) 273 | (setq expected (dash--expected expected err)) 274 | (with-output-to-string 275 | (with-current-buffer standard-output 276 | (dash--lisp-to-md actual) 277 | (insert " ;; ") 278 | (cond ((memq op '(=> ~>)) 279 | (princ op) 280 | (insert ?\s) 281 | (dash--lisp-to-md expected)) 282 | (err (princ expected)) 283 | ((error "Invalid test case: %S" example))))))) 284 | 285 | (defun dash--example-to-texi (example) 286 | "Return a Texinfo string documenting EXAMPLE." 287 | (pcase-let* ((`(,actual ,op ,expected) example) 288 | (err (eq op '!!>))) 289 | (setq expected (dash--expected expected err)) 290 | (with-output-to-string 291 | (with-current-buffer standard-output 292 | (insert "@group\n") 293 | (dash--lisp-to-texi actual) 294 | (insert "\n " (if err "@error{}" "@result{}") ?\s) 295 | (funcall (if err #'princ #'dash--lisp-to-texi) expected) 296 | (insert "\n@end group"))))) 297 | 298 | (defun dash--group-to-md (group) 299 | "Return a Markdown string documenting GROUP." 300 | (pcase group 301 | (`(,(and (pred stringp) name) . ,doc) 302 | (concat "## " name "\n\n" (dash--docstring-to-md doc) "\n")) 303 | ((and `(,fn . ,examples) 304 | (let `(,sig . ,doc) (dash--describe fn))) 305 | (format "#### %s `%s`\n\n%s\n\n```el\n%s\n```\n" 306 | fn sig (dash--docstring-to-md doc) 307 | (mapconcat #'dash--example-to-md (-take 3 examples) "\n"))))) 308 | 309 | (defun dash--group-to-texi (group) 310 | "Return a Texinfo string documenting GROUP." 311 | ;; Added in Emacs 24.4. 312 | (declare-function macrop "subr" (object)) 313 | (pcase group 314 | (`(,(and (pred stringp) name) . ,doc) 315 | (concat "@node " name "\n@section " name "\n\n" 316 | (dash--docstring-to-texi doc) "\n")) 317 | ((and `(,fn . ,examples) 318 | (let `(,sig . ,doc) (dash--describe fn)) 319 | (let type (if (macrop fn) "defmac" "defun"))) 320 | (format (concat "@anchor{%s}\n" 321 | "@%s %s %s\n" 322 | "%s\n\n" 323 | "@example\n%s\n@end example\n" 324 | "@end %s\n") 325 | fn type fn sig (dash--docstring-to-texi doc) 326 | (mapconcat #'dash--example-to-texi (-take 3 examples) "\n") 327 | type)))) 328 | 329 | (defun dash--summary-to-md (group) 330 | "Return a Markdown string summarizing GROUP." 331 | (pcase group 332 | (`(,(and (pred stringp) name) . ,doc) 333 | (concat "\n### " name "\n\n" (dash--docstring-to-md doc) "\n")) 334 | ((and `(,fn . ,_) (let sig (car (dash--describe fn)))) 335 | (format "* %s `%s`" (dash--github-link fn) sig)))) 336 | 337 | (autoload 'lm-version "lisp-mnt") 338 | 339 | (defun dash--make-md () 340 | "Generate Markdown README." 341 | (with-temp-file "README.md" 342 | (insert-file-contents "readme-template.md") 343 | (dash--replace-all "[[ dash-version ]]" (lm-version "dash.el")) 344 | (dash--replace-all "[[ function-list ]]" 345 | (mapconcat #'dash--summary-to-md dash--groups "\n")) 346 | (dash--replace-all "[[ function-docs ]]" 347 | (mapconcat #'dash--group-to-md dash--groups "\n")))) 348 | 349 | (defun dash--make-texi () 350 | "Generate Texinfo manual." 351 | (with-temp-file "dash.texi" 352 | (insert-file-contents "dash-template.texi") 353 | (dash--replace-all "@c [[ dash-version ]]" (lm-version "dash.el")) 354 | (dash--replace-all 355 | "@c [[ function-list ]]" 356 | (mapconcat (lambda (group) (concat "* " (car group) "::")) 357 | (--filter (stringp (car it)) dash--groups) 358 | "\n")) 359 | (dash--replace-all "@c [[ function-docs ]]" 360 | (mapconcat #'dash--group-to-texi dash--groups "\n")))) 361 | 362 | (defun dash-make-docs () 363 | "Generate Dash Markdown README and Texinfo manual." 364 | (let ((dash--groups (reverse dash--groups)) 365 | (case-fold-search nil)) 366 | (dash--make-md) 367 | (dash--make-texi))) 368 | 369 | (provide 'dash-defs) 370 | 371 | ;;; dash-defs.el ends here 372 | -------------------------------------------------------------------------------- /doc/fdl.texi: -------------------------------------------------------------------------------- 1 | @c The GNU Free Documentation License. 2 | @center Version 1.3, 3 November 2008 3 | 4 | @c This file is intended to be included within another document, 5 | @c hence no sectioning command or @node. 6 | 7 | @display 8 | Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 9 | @uref{https://fsf.org/} 10 | 11 | Everyone is permitted to copy and distribute verbatim copies 12 | of this license document, but changing it is not allowed. 13 | @end display 14 | 15 | @enumerate 0 16 | @item 17 | PREAMBLE 18 | 19 | The purpose of this License is to make a manual, textbook, or other 20 | functional and useful document @dfn{free} in the sense of freedom: to 21 | assure everyone the effective freedom to copy and redistribute it, 22 | with or without modifying it, either commercially or noncommercially. 23 | Secondarily, this License preserves for the author and publisher a way 24 | to get credit for their work, while not being considered responsible 25 | for modifications made by others. 26 | 27 | This License is a kind of ``copyleft'', which means that derivative 28 | works of the document must themselves be free in the same sense. It 29 | complements the GNU General Public License, which is a copyleft 30 | license designed for free software. 31 | 32 | We have designed this License in order to use it for manuals for free 33 | software, because free software needs free documentation: a free 34 | program should come with manuals providing the same freedoms that the 35 | software does. But this License is not limited to software manuals; 36 | it can be used for any textual work, regardless of subject matter or 37 | whether it is published as a printed book. We recommend this License 38 | principally for works whose purpose is instruction or reference. 39 | 40 | @item 41 | APPLICABILITY AND DEFINITIONS 42 | 43 | This License applies to any manual or other work, in any medium, that 44 | contains a notice placed by the copyright holder saying it can be 45 | distributed under the terms of this License. Such a notice grants a 46 | world-wide, royalty-free license, unlimited in duration, to use that 47 | work under the conditions stated herein. The ``Document'', below, 48 | refers to any such manual or work. Any member of the public is a 49 | licensee, and is addressed as ``you''. You accept the license if you 50 | copy, modify or distribute the work in a way requiring permission 51 | under copyright law. 52 | 53 | A ``Modified Version'' of the Document means any work containing the 54 | Document or a portion of it, either copied verbatim, or with 55 | modifications and/or translated into another language. 56 | 57 | A ``Secondary Section'' is a named appendix or a front-matter section 58 | of the Document that deals exclusively with the relationship of the 59 | publishers or authors of the Document to the Document's overall 60 | subject (or to related matters) and contains nothing that could fall 61 | directly within that overall subject. (Thus, if the Document is in 62 | part a textbook of mathematics, a Secondary Section may not explain 63 | any mathematics.) The relationship could be a matter of historical 64 | connection with the subject or with related matters, or of legal, 65 | commercial, philosophical, ethical or political position regarding 66 | them. 67 | 68 | The ``Invariant Sections'' are certain Secondary Sections whose titles 69 | are designated, as being those of Invariant Sections, in the notice 70 | that says that the Document is released under this License. If a 71 | section does not fit the above definition of Secondary then it is not 72 | allowed to be designated as Invariant. The Document may contain zero 73 | Invariant Sections. If the Document does not identify any Invariant 74 | Sections then there are none. 75 | 76 | The ``Cover Texts'' are certain short passages of text that are listed, 77 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that 78 | the Document is released under this License. A Front-Cover Text may 79 | be at most 5 words, and a Back-Cover Text may be at most 25 words. 80 | 81 | A ``Transparent'' copy of the Document means a machine-readable copy, 82 | represented in a format whose specification is available to the 83 | general public, that is suitable for revising the document 84 | straightforwardly with generic text editors or (for images composed of 85 | pixels) generic paint programs or (for drawings) some widely available 86 | drawing editor, and that is suitable for input to text formatters or 87 | for automatic translation to a variety of formats suitable for input 88 | to text formatters. A copy made in an otherwise Transparent file 89 | format whose markup, or absence of markup, has been arranged to thwart 90 | or discourage subsequent modification by readers is not Transparent. 91 | An image format is not Transparent if used for any substantial amount 92 | of text. A copy that is not ``Transparent'' is called ``Opaque''. 93 | 94 | Examples of suitable formats for Transparent copies include plain 95 | ASCII without markup, Texinfo input format, La@TeX{} input 96 | format, SGML or XML using a publicly available 97 | DTD, and standard-conforming simple HTML, 98 | PostScript or PDF designed for human modification. Examples 99 | of transparent image formats include PNG, XCF and 100 | JPG@. Opaque formats include proprietary formats that can be 101 | read and edited only by proprietary word processors, SGML or 102 | XML for which the DTD and/or processing tools are 103 | not generally available, and the machine-generated HTML, 104 | PostScript or PDF produced by some word processors for 105 | output purposes only. 106 | 107 | The ``Title Page'' means, for a printed book, the title page itself, 108 | plus such following pages as are needed to hold, legibly, the material 109 | this License requires to appear in the title page. For works in 110 | formats which do not have any title page as such, ``Title Page'' means 111 | the text near the most prominent appearance of the work's title, 112 | preceding the beginning of the body of the text. 113 | 114 | The ``publisher'' means any person or entity that distributes copies 115 | of the Document to the public. 116 | 117 | A section ``Entitled XYZ'' means a named subunit of the Document whose 118 | title either is precisely XYZ or contains XYZ in parentheses following 119 | text that translates XYZ in another language. (Here XYZ stands for a 120 | specific section name mentioned below, such as ``Acknowledgements'', 121 | ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' 122 | of such a section when you modify the Document means that it remains a 123 | section ``Entitled XYZ'' according to this definition. 124 | 125 | The Document may include Warranty Disclaimers next to the notice which 126 | states that this License applies to the Document. These Warranty 127 | Disclaimers are considered to be included by reference in this 128 | License, but only as regards disclaiming warranties: any other 129 | implication that these Warranty Disclaimers may have is void and has 130 | no effect on the meaning of this License. 131 | 132 | @item 133 | VERBATIM COPYING 134 | 135 | You may copy and distribute the Document in any medium, either 136 | commercially or noncommercially, provided that this License, the 137 | copyright notices, and the license notice saying this License applies 138 | to the Document are reproduced in all copies, and that you add no other 139 | conditions whatsoever to those of this License. You may not use 140 | technical measures to obstruct or control the reading or further 141 | copying of the copies you make or distribute. However, you may accept 142 | compensation in exchange for copies. If you distribute a large enough 143 | number of copies you must also follow the conditions in section 3. 144 | 145 | You may also lend copies, under the same conditions stated above, and 146 | you may publicly display copies. 147 | 148 | @item 149 | COPYING IN QUANTITY 150 | 151 | If you publish printed copies (or copies in media that commonly have 152 | printed covers) of the Document, numbering more than 100, and the 153 | Document's license notice requires Cover Texts, you must enclose the 154 | copies in covers that carry, clearly and legibly, all these Cover 155 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 156 | the back cover. Both covers must also clearly and legibly identify 157 | you as the publisher of these copies. The front cover must present 158 | the full title with all words of the title equally prominent and 159 | visible. You may add other material on the covers in addition. 160 | Copying with changes limited to the covers, as long as they preserve 161 | the title of the Document and satisfy these conditions, can be treated 162 | as verbatim copying in other respects. 163 | 164 | If the required texts for either cover are too voluminous to fit 165 | legibly, you should put the first ones listed (as many as fit 166 | reasonably) on the actual cover, and continue the rest onto adjacent 167 | pages. 168 | 169 | If you publish or distribute Opaque copies of the Document numbering 170 | more than 100, you must either include a machine-readable Transparent 171 | copy along with each Opaque copy, or state in or with each Opaque copy 172 | a computer-network location from which the general network-using 173 | public has access to download using public-standard network protocols 174 | a complete Transparent copy of the Document, free of added material. 175 | If you use the latter option, you must take reasonably prudent steps, 176 | when you begin distribution of Opaque copies in quantity, to ensure 177 | that this Transparent copy will remain thus accessible at the stated 178 | location until at least one year after the last time you distribute an 179 | Opaque copy (directly or through your agents or retailers) of that 180 | edition to the public. 181 | 182 | It is requested, but not required, that you contact the authors of the 183 | Document well before redistributing any large number of copies, to give 184 | them a chance to provide you with an updated version of the Document. 185 | 186 | @item 187 | MODIFICATIONS 188 | 189 | You may copy and distribute a Modified Version of the Document under 190 | the conditions of sections 2 and 3 above, provided that you release 191 | the Modified Version under precisely this License, with the Modified 192 | Version filling the role of the Document, thus licensing distribution 193 | and modification of the Modified Version to whoever possesses a copy 194 | of it. In addition, you must do these things in the Modified Version: 195 | 196 | @enumerate A 197 | @item 198 | Use in the Title Page (and on the covers, if any) a title distinct 199 | from that of the Document, and from those of previous versions 200 | (which should, if there were any, be listed in the History section 201 | of the Document). You may use the same title as a previous version 202 | if the original publisher of that version gives permission. 203 | 204 | @item 205 | List on the Title Page, as authors, one or more persons or entities 206 | responsible for authorship of the modifications in the Modified 207 | Version, together with at least five of the principal authors of the 208 | Document (all of its principal authors, if it has fewer than five), 209 | unless they release you from this requirement. 210 | 211 | @item 212 | State on the Title page the name of the publisher of the 213 | Modified Version, as the publisher. 214 | 215 | @item 216 | Preserve all the copyright notices of the Document. 217 | 218 | @item 219 | Add an appropriate copyright notice for your modifications 220 | adjacent to the other copyright notices. 221 | 222 | @item 223 | Include, immediately after the copyright notices, a license notice 224 | giving the public permission to use the Modified Version under the 225 | terms of this License, in the form shown in the Addendum below. 226 | 227 | @item 228 | Preserve in that license notice the full lists of Invariant Sections 229 | and required Cover Texts given in the Document's license notice. 230 | 231 | @item 232 | Include an unaltered copy of this License. 233 | 234 | @item 235 | Preserve the section Entitled ``History'', Preserve its Title, and add 236 | to it an item stating at least the title, year, new authors, and 237 | publisher of the Modified Version as given on the Title Page. If 238 | there is no section Entitled ``History'' in the Document, create one 239 | stating the title, year, authors, and publisher of the Document as 240 | given on its Title Page, then add an item describing the Modified 241 | Version as stated in the previous sentence. 242 | 243 | @item 244 | Preserve the network location, if any, given in the Document for 245 | public access to a Transparent copy of the Document, and likewise 246 | the network locations given in the Document for previous versions 247 | it was based on. These may be placed in the ``History'' section. 248 | You may omit a network location for a work that was published at 249 | least four years before the Document itself, or if the original 250 | publisher of the version it refers to gives permission. 251 | 252 | @item 253 | For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve 254 | the Title of the section, and preserve in the section all the 255 | substance and tone of each of the contributor acknowledgements and/or 256 | dedications given therein. 257 | 258 | @item 259 | Preserve all the Invariant Sections of the Document, 260 | unaltered in their text and in their titles. Section numbers 261 | or the equivalent are not considered part of the section titles. 262 | 263 | @item 264 | Delete any section Entitled ``Endorsements''. Such a section 265 | may not be included in the Modified Version. 266 | 267 | @item 268 | Do not retitle any existing section to be Entitled ``Endorsements'' or 269 | to conflict in title with any Invariant Section. 270 | 271 | @item 272 | Preserve any Warranty Disclaimers. 273 | @end enumerate 274 | 275 | If the Modified Version includes new front-matter sections or 276 | appendices that qualify as Secondary Sections and contain no material 277 | copied from the Document, you may at your option designate some or all 278 | of these sections as invariant. To do this, add their titles to the 279 | list of Invariant Sections in the Modified Version's license notice. 280 | These titles must be distinct from any other section titles. 281 | 282 | You may add a section Entitled ``Endorsements'', provided it contains 283 | nothing but endorsements of your Modified Version by various 284 | parties---for example, statements of peer review or that the text has 285 | been approved by an organization as the authoritative definition of a 286 | standard. 287 | 288 | You may add a passage of up to five words as a Front-Cover Text, and a 289 | passage of up to 25 words as a Back-Cover Text, to the end of the list 290 | of Cover Texts in the Modified Version. Only one passage of 291 | Front-Cover Text and one of Back-Cover Text may be added by (or 292 | through arrangements made by) any one entity. If the Document already 293 | includes a cover text for the same cover, previously added by you or 294 | by arrangement made by the same entity you are acting on behalf of, 295 | you may not add another; but you may replace the old one, on explicit 296 | permission from the previous publisher that added the old one. 297 | 298 | The author(s) and publisher(s) of the Document do not by this License 299 | give permission to use their names for publicity for or to assert or 300 | imply endorsement of any Modified Version. 301 | 302 | @item 303 | COMBINING DOCUMENTS 304 | 305 | You may combine the Document with other documents released under this 306 | License, under the terms defined in section 4 above for modified 307 | versions, provided that you include in the combination all of the 308 | Invariant Sections of all of the original documents, unmodified, and 309 | list them all as Invariant Sections of your combined work in its 310 | license notice, and that you preserve all their Warranty Disclaimers. 311 | 312 | The combined work need only contain one copy of this License, and 313 | multiple identical Invariant Sections may be replaced with a single 314 | copy. If there are multiple Invariant Sections with the same name but 315 | different contents, make the title of each such section unique by 316 | adding at the end of it, in parentheses, the name of the original 317 | author or publisher of that section if known, or else a unique number. 318 | Make the same adjustment to the section titles in the list of 319 | Invariant Sections in the license notice of the combined work. 320 | 321 | In the combination, you must combine any sections Entitled ``History'' 322 | in the various original documents, forming one section Entitled 323 | ``History''; likewise combine any sections Entitled ``Acknowledgements'', 324 | and any sections Entitled ``Dedications''. You must delete all 325 | sections Entitled ``Endorsements.'' 326 | 327 | @item 328 | COLLECTIONS OF DOCUMENTS 329 | 330 | You may make a collection consisting of the Document and other documents 331 | released under this License, and replace the individual copies of this 332 | License in the various documents with a single copy that is included in 333 | the collection, provided that you follow the rules of this License for 334 | verbatim copying of each of the documents in all other respects. 335 | 336 | You may extract a single document from such a collection, and distribute 337 | it individually under this License, provided you insert a copy of this 338 | License into the extracted document, and follow this License in all 339 | other respects regarding verbatim copying of that document. 340 | 341 | @item 342 | AGGREGATION WITH INDEPENDENT WORKS 343 | 344 | A compilation of the Document or its derivatives with other separate 345 | and independent documents or works, in or on a volume of a storage or 346 | distribution medium, is called an ``aggregate'' if the copyright 347 | resulting from the compilation is not used to limit the legal rights 348 | of the compilation's users beyond what the individual works permit. 349 | When the Document is included in an aggregate, this License does not 350 | apply to the other works in the aggregate which are not themselves 351 | derivative works of the Document. 352 | 353 | If the Cover Text requirement of section 3 is applicable to these 354 | copies of the Document, then if the Document is less than one half of 355 | the entire aggregate, the Document's Cover Texts may be placed on 356 | covers that bracket the Document within the aggregate, or the 357 | electronic equivalent of covers if the Document is in electronic form. 358 | Otherwise they must appear on printed covers that bracket the whole 359 | aggregate. 360 | 361 | @item 362 | TRANSLATION 363 | 364 | Translation is considered a kind of modification, so you may 365 | distribute translations of the Document under the terms of section 4. 366 | Replacing Invariant Sections with translations requires special 367 | permission from their copyright holders, but you may include 368 | translations of some or all Invariant Sections in addition to the 369 | original versions of these Invariant Sections. You may include a 370 | translation of this License, and all the license notices in the 371 | Document, and any Warranty Disclaimers, provided that you also include 372 | the original English version of this License and the original versions 373 | of those notices and disclaimers. In case of a disagreement between 374 | the translation and the original version of this License or a notice 375 | or disclaimer, the original version will prevail. 376 | 377 | If a section in the Document is Entitled ``Acknowledgements'', 378 | ``Dedications'', or ``History'', the requirement (section 4) to Preserve 379 | its Title (section 1) will typically require changing the actual 380 | title. 381 | 382 | @item 383 | TERMINATION 384 | 385 | You may not copy, modify, sublicense, or distribute the Document 386 | except as expressly provided under this License. Any attempt 387 | otherwise to copy, modify, sublicense, or distribute it is void, and 388 | will automatically terminate your rights under this License. 389 | 390 | However, if you cease all violation of this License, then your license 391 | from a particular copyright holder is reinstated (a) provisionally, 392 | unless and until the copyright holder explicitly and finally 393 | terminates your license, and (b) permanently, if the copyright holder 394 | fails to notify you of the violation by some reasonable means prior to 395 | 60 days after the cessation. 396 | 397 | Moreover, your license from a particular copyright holder is 398 | reinstated permanently if the copyright holder notifies you of the 399 | violation by some reasonable means, this is the first time you have 400 | received notice of violation of this License (for any work) from that 401 | copyright holder, and you cure the violation prior to 30 days after 402 | your receipt of the notice. 403 | 404 | Termination of your rights under this section does not terminate the 405 | licenses of parties who have received copies or rights from you under 406 | this License. If your rights have been terminated and not permanently 407 | reinstated, receipt of a copy of some or all of the same material does 408 | not give you any rights to use it. 409 | 410 | @item 411 | FUTURE REVISIONS OF THIS LICENSE 412 | 413 | The Free Software Foundation may publish new, revised versions 414 | of the GNU Free Documentation License from time to time. Such new 415 | versions will be similar in spirit to the present version, but may 416 | differ in detail to address new problems or concerns. See 417 | @uref{https://www.gnu.org/licenses/}. 418 | 419 | Each version of the License is given a distinguishing version number. 420 | If the Document specifies that a particular numbered version of this 421 | License ``or any later version'' applies to it, you have the option of 422 | following the terms and conditions either of that specified version or 423 | of any later version that has been published (not as a draft) by the 424 | Free Software Foundation. If the Document does not specify a version 425 | number of this License, you may choose any version ever published (not 426 | as a draft) by the Free Software Foundation. If the Document 427 | specifies that a proxy can decide which future versions of this 428 | License can be used, that proxy's public statement of acceptance of a 429 | version permanently authorizes you to choose that version for the 430 | Document. 431 | 432 | @item 433 | RELICENSING 434 | 435 | ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any 436 | World Wide Web server that publishes copyrightable works and also 437 | provides prominent facilities for anybody to edit those works. A 438 | public wiki that anybody can edit is an example of such a server. A 439 | ``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the 440 | site means any set of copyrightable works thus published on the MMC 441 | site. 442 | 443 | ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 444 | license published by Creative Commons Corporation, a not-for-profit 445 | corporation with a principal place of business in San Francisco, 446 | California, as well as future copyleft versions of that license 447 | published by that same organization. 448 | 449 | ``Incorporate'' means to publish or republish a Document, in whole or 450 | in part, as part of another Document. 451 | 452 | An MMC is ``eligible for relicensing'' if it is licensed under this 453 | License, and if all works that were first published under this License 454 | somewhere other than this MMC, and subsequently incorporated in whole 455 | or in part into the MMC, (1) had no cover texts or invariant sections, 456 | and (2) were thus incorporated prior to November 1, 2008. 457 | 458 | The operator of an MMC Site may republish an MMC contained in the site 459 | under CC-BY-SA on the same site at any time before August 1, 2009, 460 | provided the MMC is eligible for relicensing. 461 | 462 | @end enumerate 463 | 464 | @page 465 | @heading ADDENDUM: How to use this License for your documents 466 | 467 | To use this License in a document you have written, include a copy of 468 | the License in the document and put the following copyright and 469 | license notices just after the title page: 470 | 471 | @smallexample 472 | @group 473 | Copyright (C) @var{year} @var{your name}. 474 | Permission is granted to copy, distribute and/or modify this document 475 | under the terms of the GNU Free Documentation License, Version 1.3 476 | or any later version published by the Free Software Foundation; 477 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 478 | Texts. A copy of the license is included in the section entitled ``GNU 479 | Free Documentation License''. 480 | @end group 481 | @end smallexample 482 | 483 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 484 | replace the ``with@dots{}Texts.''@: line with this: 485 | 486 | @smallexample 487 | @group 488 | with the Invariant Sections being @var{list their titles}, with 489 | the Front-Cover Texts being @var{list}, and with the Back-Cover Texts 490 | being @var{list}. 491 | @end group 492 | @end smallexample 493 | 494 | If you have Invariant Sections without Cover Texts, or some other 495 | combination of the three, merge those two alternatives to suit the 496 | situation. 497 | 498 | If your document contains nontrivial examples of program code, we 499 | recommend releasing these examples in parallel under your choice of 500 | free software license, such as the GNU General Public License, 501 | to permit their use in free software. 502 | 503 | @c Local Variables: 504 | @c ispell-local-pdict: "ispell-dict" 505 | @c End: 506 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /doc/gpl.texi: -------------------------------------------------------------------------------- 1 | @c The GNU General Public License. 2 | @center Version 3, 29 June 2007 3 | 4 | @c This file is intended to be included within another document, 5 | @c hence no sectioning command or @node. 6 | 7 | @display 8 | Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/} 9 | 10 | Everyone is permitted to copy and distribute verbatim copies of this 11 | license document, but changing it is not allowed. 12 | @end display 13 | 14 | @heading Preamble 15 | 16 | The GNU General Public License is a free, copyleft license for 17 | software and other kinds of works. 18 | 19 | The licenses for most software and other practical works are designed 20 | to take away your freedom to share and change the works. By contrast, 21 | the GNU General Public License is intended to guarantee your freedom 22 | to share and change all versions of a program---to make sure it remains 23 | free software for all its users. We, the Free Software Foundation, 24 | use the GNU General Public License for most of our software; it 25 | applies also to any other work released this way by its authors. You 26 | can apply it to your programs, too. 27 | 28 | When we speak of free software, we are referring to freedom, not 29 | price. Our General Public Licenses are designed to make sure that you 30 | have the freedom to distribute copies of free software (and charge for 31 | them if you wish), that you receive source code or can get it if you 32 | want it, that you can change the software or use pieces of it in new 33 | free programs, and that you know you can do these things. 34 | 35 | To protect your rights, we need to prevent others from denying you 36 | these rights or asking you to surrender the rights. Therefore, you 37 | have certain responsibilities if you distribute copies of the 38 | software, or if you modify it: responsibilities to respect the freedom 39 | of others. 40 | 41 | For example, if you distribute copies of such a program, whether 42 | gratis or for a fee, you must pass on to the recipients the same 43 | freedoms that you received. You must make sure that they, too, 44 | receive or can get the source code. And you must show them these 45 | terms so they know their rights. 46 | 47 | Developers that use the GNU GPL protect your rights with two steps: 48 | (1) assert copyright on the software, and (2) offer you this License 49 | giving you legal permission to copy, distribute and/or modify it. 50 | 51 | For the developers' and authors' protection, the GPL clearly explains 52 | that there is no warranty for this free software. For both users' and 53 | authors' sake, the GPL requires that modified versions be marked as 54 | changed, so that their problems will not be attributed erroneously to 55 | authors of previous versions. 56 | 57 | Some devices are designed to deny users access to install or run 58 | modified versions of the software inside them, although the 59 | manufacturer can do so. This is fundamentally incompatible with the 60 | aim of protecting users' freedom to change the software. The 61 | systematic pattern of such abuse occurs in the area of products for 62 | individuals to use, which is precisely where it is most unacceptable. 63 | Therefore, we have designed this version of the GPL to prohibit the 64 | practice for those products. If such problems arise substantially in 65 | other domains, we stand ready to extend this provision to those 66 | domains in future versions of the GPL, as needed to protect the 67 | freedom of users. 68 | 69 | Finally, every program is threatened constantly by software patents. 70 | States should not allow patents to restrict development and use of 71 | software on general-purpose computers, but in those that do, we wish 72 | to avoid the special danger that patents applied to a free program 73 | could make it effectively proprietary. To prevent this, the GPL 74 | assures that patents cannot be used to render the program non-free. 75 | 76 | The precise terms and conditions for copying, distribution and 77 | modification follow. 78 | 79 | @heading TERMS AND CONDITIONS 80 | 81 | @enumerate 0 82 | @item Definitions. 83 | 84 | ``This License'' refers to version 3 of the GNU General Public License. 85 | 86 | ``Copyright'' also means copyright-like laws that apply to other kinds 87 | of works, such as semiconductor masks. 88 | 89 | ``The Program'' refers to any copyrightable work licensed under this 90 | License. Each licensee is addressed as ``you''. ``Licensees'' and 91 | ``recipients'' may be individuals or organizations. 92 | 93 | To ``modify'' a work means to copy from or adapt all or part of the work 94 | in a fashion requiring copyright permission, other than the making of 95 | an exact copy. The resulting work is called a ``modified version'' of 96 | the earlier work or a work ``based on'' the earlier work. 97 | 98 | A ``covered work'' means either the unmodified Program or a work based 99 | on the Program. 100 | 101 | To ``propagate'' a work means to do anything with it that, without 102 | permission, would make you directly or secondarily liable for 103 | infringement under applicable copyright law, except executing it on a 104 | computer or modifying a private copy. Propagation includes copying, 105 | distribution (with or without modification), making available to the 106 | public, and in some countries other activities as well. 107 | 108 | To ``convey'' a work means any kind of propagation that enables other 109 | parties to make or receive copies. Mere interaction with a user 110 | through a computer network, with no transfer of a copy, is not 111 | conveying. 112 | 113 | An interactive user interface displays ``Appropriate Legal Notices'' to 114 | the extent that it includes a convenient and prominently visible 115 | feature that (1) displays an appropriate copyright notice, and (2) 116 | tells the user that there is no warranty for the work (except to the 117 | extent that warranties are provided), that licensees may convey the 118 | work under this License, and how to view a copy of this License. If 119 | the interface presents a list of user commands or options, such as a 120 | menu, a prominent item in the list meets this criterion. 121 | 122 | @item Source Code. 123 | 124 | The ``source code'' for a work means the preferred form of the work for 125 | making modifications to it. ``Object code'' means any non-source form 126 | of a work. 127 | 128 | A ``Standard Interface'' means an interface that either is an official 129 | standard defined by a recognized standards body, or, in the case of 130 | interfaces specified for a particular programming language, one that 131 | is widely used among developers working in that language. 132 | 133 | The ``System Libraries'' of an executable work include anything, other 134 | than the work as a whole, that (a) is included in the normal form of 135 | packaging a Major Component, but which is not part of that Major 136 | Component, and (b) serves only to enable use of the work with that 137 | Major Component, or to implement a Standard Interface for which an 138 | implementation is available to the public in source code form. A 139 | ``Major Component'', in this context, means a major essential component 140 | (kernel, window system, and so on) of the specific operating system 141 | (if any) on which the executable work runs, or a compiler used to 142 | produce the work, or an object code interpreter used to run it. 143 | 144 | The ``Corresponding Source'' for a work in object code form means all 145 | the source code needed to generate, install, and (for an executable 146 | work) run the object code and to modify the work, including scripts to 147 | control those activities. However, it does not include the work's 148 | System Libraries, or general-purpose tools or generally available free 149 | programs which are used unmodified in performing those activities but 150 | which are not part of the work. For example, Corresponding Source 151 | includes interface definition files associated with source files for 152 | the work, and the source code for shared libraries and dynamically 153 | linked subprograms that the work is specifically designed to require, 154 | such as by intimate data communication or control flow between those 155 | subprograms and other parts of the work. 156 | 157 | The Corresponding Source need not include anything that users can 158 | regenerate automatically from other parts of the Corresponding Source. 159 | 160 | The Corresponding Source for a work in source code form is that same 161 | work. 162 | 163 | @item Basic Permissions. 164 | 165 | All rights granted under this License are granted for the term of 166 | copyright on the Program, and are irrevocable provided the stated 167 | conditions are met. This License explicitly affirms your unlimited 168 | permission to run the unmodified Program. The output from running a 169 | covered work is covered by this License only if the output, given its 170 | content, constitutes a covered work. This License acknowledges your 171 | rights of fair use or other equivalent, as provided by copyright law. 172 | 173 | You may make, run and propagate covered works that you do not convey, 174 | without conditions so long as your license otherwise remains in force. 175 | You may convey covered works to others for the sole purpose of having 176 | them make modifications exclusively for you, or provide you with 177 | facilities for running those works, provided that you comply with the 178 | terms of this License in conveying all material for which you do not 179 | control copyright. Those thus making or running the covered works for 180 | you must do so exclusively on your behalf, under your direction and 181 | control, on terms that prohibit them from making any copies of your 182 | copyrighted material outside their relationship with you. 183 | 184 | Conveying under any other circumstances is permitted solely under the 185 | conditions stated below. Sublicensing is not allowed; section 10 186 | makes it unnecessary. 187 | 188 | @item Protecting Users' Legal Rights From Anti-Circumvention Law. 189 | 190 | No covered work shall be deemed part of an effective technological 191 | measure under any applicable law fulfilling obligations under article 192 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 193 | similar laws prohibiting or restricting circumvention of such 194 | measures. 195 | 196 | When you convey a covered work, you waive any legal power to forbid 197 | circumvention of technological measures to the extent such 198 | circumvention is effected by exercising rights under this License with 199 | respect to the covered work, and you disclaim any intention to limit 200 | operation or modification of the work as a means of enforcing, against 201 | the work's users, your or third parties' legal rights to forbid 202 | circumvention of technological measures. 203 | 204 | @item Conveying Verbatim Copies. 205 | 206 | You may convey verbatim copies of the Program's source code as you 207 | receive it, in any medium, provided that you conspicuously and 208 | appropriately publish on each copy an appropriate copyright notice; 209 | keep intact all notices stating that this License and any 210 | non-permissive terms added in accord with section 7 apply to the code; 211 | keep intact all notices of the absence of any warranty; and give all 212 | recipients a copy of this License along with the Program. 213 | 214 | You may charge any price or no price for each copy that you convey, 215 | and you may offer support or warranty protection for a fee. 216 | 217 | @item Conveying Modified Source Versions. 218 | 219 | You may convey a work based on the Program, or the modifications to 220 | produce it from the Program, in the form of source code under the 221 | terms of section 4, provided that you also meet all of these 222 | conditions: 223 | 224 | @enumerate a 225 | @item 226 | The work must carry prominent notices stating that you modified it, 227 | and giving a relevant date. 228 | 229 | @item 230 | The work must carry prominent notices stating that it is released 231 | under this License and any conditions added under section 7. This 232 | requirement modifies the requirement in section 4 to ``keep intact all 233 | notices''. 234 | 235 | @item 236 | You must license the entire work, as a whole, under this License to 237 | anyone who comes into possession of a copy. This License will 238 | therefore apply, along with any applicable section 7 additional terms, 239 | to the whole of the work, and all its parts, regardless of how they 240 | are packaged. This License gives no permission to license the work in 241 | any other way, but it does not invalidate such permission if you have 242 | separately received it. 243 | 244 | @item 245 | If the work has interactive user interfaces, each must display 246 | Appropriate Legal Notices; however, if the Program has interactive 247 | interfaces that do not display Appropriate Legal Notices, your work 248 | need not make them do so. 249 | @end enumerate 250 | 251 | A compilation of a covered work with other separate and independent 252 | works, which are not by their nature extensions of the covered work, 253 | and which are not combined with it such as to form a larger program, 254 | in or on a volume of a storage or distribution medium, is called an 255 | ``aggregate'' if the compilation and its resulting copyright are not 256 | used to limit the access or legal rights of the compilation's users 257 | beyond what the individual works permit. Inclusion of a covered work 258 | in an aggregate does not cause this License to apply to the other 259 | parts of the aggregate. 260 | 261 | @item Conveying Non-Source Forms. 262 | 263 | You may convey a covered work in object code form under the terms of 264 | sections 4 and 5, provided that you also convey the machine-readable 265 | Corresponding Source under the terms of this License, in one of these 266 | ways: 267 | 268 | @enumerate a 269 | @item 270 | Convey the object code in, or embodied in, a physical product 271 | (including a physical distribution medium), accompanied by the 272 | Corresponding Source fixed on a durable physical medium customarily 273 | used for software interchange. 274 | 275 | @item 276 | Convey the object code in, or embodied in, a physical product 277 | (including a physical distribution medium), accompanied by a written 278 | offer, valid for at least three years and valid for as long as you 279 | offer spare parts or customer support for that product model, to give 280 | anyone who possesses the object code either (1) a copy of the 281 | Corresponding Source for all the software in the product that is 282 | covered by this License, on a durable physical medium customarily used 283 | for software interchange, for a price no more than your reasonable 284 | cost of physically performing this conveying of source, or (2) access 285 | to copy the Corresponding Source from a network server at no charge. 286 | 287 | @item 288 | Convey individual copies of the object code with a copy of the written 289 | offer to provide the Corresponding Source. This alternative is 290 | allowed only occasionally and noncommercially, and only if you 291 | received the object code with such an offer, in accord with subsection 292 | 6b. 293 | 294 | @item 295 | Convey the object code by offering access from a designated place 296 | (gratis or for a charge), and offer equivalent access to the 297 | Corresponding Source in the same way through the same place at no 298 | further charge. You need not require recipients to copy the 299 | Corresponding Source along with the object code. If the place to copy 300 | the object code is a network server, the Corresponding Source may be 301 | on a different server (operated by you or a third party) that supports 302 | equivalent copying facilities, provided you maintain clear directions 303 | next to the object code saying where to find the Corresponding Source. 304 | Regardless of what server hosts the Corresponding Source, you remain 305 | obligated to ensure that it is available for as long as needed to 306 | satisfy these requirements. 307 | 308 | @item 309 | Convey the object code using peer-to-peer transmission, provided you 310 | inform other peers where the object code and Corresponding Source of 311 | the work are being offered to the general public at no charge under 312 | subsection 6d. 313 | 314 | @end enumerate 315 | 316 | A separable portion of the object code, whose source code is excluded 317 | from the Corresponding Source as a System Library, need not be 318 | included in conveying the object code work. 319 | 320 | A ``User Product'' is either (1) a ``consumer product'', which means any 321 | tangible personal property which is normally used for personal, 322 | family, or household purposes, or (2) anything designed or sold for 323 | incorporation into a dwelling. In determining whether a product is a 324 | consumer product, doubtful cases shall be resolved in favor of 325 | coverage. For a particular product received by a particular user, 326 | ``normally used'' refers to a typical or common use of that class of 327 | product, regardless of the status of the particular user or of the way 328 | in which the particular user actually uses, or expects or is expected 329 | to use, the product. A product is a consumer product regardless of 330 | whether the product has substantial commercial, industrial or 331 | non-consumer uses, unless such uses represent the only significant 332 | mode of use of the product. 333 | 334 | ``Installation Information'' for a User Product means any methods, 335 | procedures, authorization keys, or other information required to 336 | install and execute modified versions of a covered work in that User 337 | Product from a modified version of its Corresponding Source. The 338 | information must suffice to ensure that the continued functioning of 339 | the modified object code is in no case prevented or interfered with 340 | solely because modification has been made. 341 | 342 | If you convey an object code work under this section in, or with, or 343 | specifically for use in, a User Product, and the conveying occurs as 344 | part of a transaction in which the right of possession and use of the 345 | User Product is transferred to the recipient in perpetuity or for a 346 | fixed term (regardless of how the transaction is characterized), the 347 | Corresponding Source conveyed under this section must be accompanied 348 | by the Installation Information. But this requirement does not apply 349 | if neither you nor any third party retains the ability to install 350 | modified object code on the User Product (for example, the work has 351 | been installed in ROM). 352 | 353 | The requirement to provide Installation Information does not include a 354 | requirement to continue to provide support service, warranty, or 355 | updates for a work that has been modified or installed by the 356 | recipient, or for the User Product in which it has been modified or 357 | installed. Access to a network may be denied when the modification 358 | itself materially and adversely affects the operation of the network 359 | or violates the rules and protocols for communication across the 360 | network. 361 | 362 | Corresponding Source conveyed, and Installation Information provided, 363 | in accord with this section must be in a format that is publicly 364 | documented (and with an implementation available to the public in 365 | source code form), and must require no special password or key for 366 | unpacking, reading or copying. 367 | 368 | @item Additional Terms. 369 | 370 | ``Additional permissions'' are terms that supplement the terms of this 371 | License by making exceptions from one or more of its conditions. 372 | Additional permissions that are applicable to the entire Program shall 373 | be treated as though they were included in this License, to the extent 374 | that they are valid under applicable law. If additional permissions 375 | apply only to part of the Program, that part may be used separately 376 | under those permissions, but the entire Program remains governed by 377 | this License without regard to the additional permissions. 378 | 379 | When you convey a copy of a covered work, you may at your option 380 | remove any additional permissions from that copy, or from any part of 381 | it. (Additional permissions may be written to require their own 382 | removal in certain cases when you modify the work.) You may place 383 | additional permissions on material, added by you to a covered work, 384 | for which you have or can give appropriate copyright permission. 385 | 386 | Notwithstanding any other provision of this License, for material you 387 | add to a covered work, you may (if authorized by the copyright holders 388 | of that material) supplement the terms of this License with terms: 389 | 390 | @enumerate a 391 | @item 392 | Disclaiming warranty or limiting liability differently from the terms 393 | of sections 15 and 16 of this License; or 394 | 395 | @item 396 | Requiring preservation of specified reasonable legal notices or author 397 | attributions in that material or in the Appropriate Legal Notices 398 | displayed by works containing it; or 399 | 400 | @item 401 | Prohibiting misrepresentation of the origin of that material, or 402 | requiring that modified versions of such material be marked in 403 | reasonable ways as different from the original version; or 404 | 405 | @item 406 | Limiting the use for publicity purposes of names of licensors or 407 | authors of the material; or 408 | 409 | @item 410 | Declining to grant rights under trademark law for use of some trade 411 | names, trademarks, or service marks; or 412 | 413 | @item 414 | Requiring indemnification of licensors and authors of that material by 415 | anyone who conveys the material (or modified versions of it) with 416 | contractual assumptions of liability to the recipient, for any 417 | liability that these contractual assumptions directly impose on those 418 | licensors and authors. 419 | @end enumerate 420 | 421 | All other non-permissive additional terms are considered ``further 422 | restrictions'' within the meaning of section 10. If the Program as you 423 | received it, or any part of it, contains a notice stating that it is 424 | governed by this License along with a term that is a further 425 | restriction, you may remove that term. If a license document contains 426 | a further restriction but permits relicensing or conveying under this 427 | License, you may add to a covered work material governed by the terms 428 | of that license document, provided that the further restriction does 429 | not survive such relicensing or conveying. 430 | 431 | If you add terms to a covered work in accord with this section, you 432 | must place, in the relevant source files, a statement of the 433 | additional terms that apply to those files, or a notice indicating 434 | where to find the applicable terms. 435 | 436 | Additional terms, permissive or non-permissive, may be stated in the 437 | form of a separately written license, or stated as exceptions; the 438 | above requirements apply either way. 439 | 440 | @item Termination. 441 | 442 | You may not propagate or modify a covered work except as expressly 443 | provided under this License. Any attempt otherwise to propagate or 444 | modify it is void, and will automatically terminate your rights under 445 | this License (including any patent licenses granted under the third 446 | paragraph of section 11). 447 | 448 | However, if you cease all violation of this License, then your license 449 | from a particular copyright holder is reinstated (a) provisionally, 450 | unless and until the copyright holder explicitly and finally 451 | terminates your license, and (b) permanently, if the copyright holder 452 | fails to notify you of the violation by some reasonable means prior to 453 | 60 days after the cessation. 454 | 455 | Moreover, your license from a particular copyright holder is 456 | reinstated permanently if the copyright holder notifies you of the 457 | violation by some reasonable means, this is the first time you have 458 | received notice of violation of this License (for any work) from that 459 | copyright holder, and you cure the violation prior to 30 days after 460 | your receipt of the notice. 461 | 462 | Termination of your rights under this section does not terminate the 463 | licenses of parties who have received copies or rights from you under 464 | this License. If your rights have been terminated and not permanently 465 | reinstated, you do not qualify to receive new licenses for the same 466 | material under section 10. 467 | 468 | @item Acceptance Not Required for Having Copies. 469 | 470 | You are not required to accept this License in order to receive or run 471 | a copy of the Program. Ancillary propagation of a covered work 472 | occurring solely as a consequence of using peer-to-peer transmission 473 | to receive a copy likewise does not require acceptance. However, 474 | nothing other than this License grants you permission to propagate or 475 | modify any covered work. These actions infringe copyright if you do 476 | not accept this License. Therefore, by modifying or propagating a 477 | covered work, you indicate your acceptance of this License to do so. 478 | 479 | @item Automatic Licensing of Downstream Recipients. 480 | 481 | Each time you convey a covered work, the recipient automatically 482 | receives a license from the original licensors, to run, modify and 483 | propagate that work, subject to this License. You are not responsible 484 | for enforcing compliance by third parties with this License. 485 | 486 | An ``entity transaction'' is a transaction transferring control of an 487 | organization, or substantially all assets of one, or subdividing an 488 | organization, or merging organizations. If propagation of a covered 489 | work results from an entity transaction, each party to that 490 | transaction who receives a copy of the work also receives whatever 491 | licenses to the work the party's predecessor in interest had or could 492 | give under the previous paragraph, plus a right to possession of the 493 | Corresponding Source of the work from the predecessor in interest, if 494 | the predecessor has it or can get it with reasonable efforts. 495 | 496 | You may not impose any further restrictions on the exercise of the 497 | rights granted or affirmed under this License. For example, you may 498 | not impose a license fee, royalty, or other charge for exercise of 499 | rights granted under this License, and you may not initiate litigation 500 | (including a cross-claim or counterclaim in a lawsuit) alleging that 501 | any patent claim is infringed by making, using, selling, offering for 502 | sale, or importing the Program or any portion of it. 503 | 504 | @item Patents. 505 | 506 | A ``contributor'' is a copyright holder who authorizes use under this 507 | License of the Program or a work on which the Program is based. The 508 | work thus licensed is called the contributor's ``contributor version''. 509 | 510 | A contributor's ``essential patent claims'' are all patent claims owned 511 | or controlled by the contributor, whether already acquired or 512 | hereafter acquired, that would be infringed by some manner, permitted 513 | by this License, of making, using, or selling its contributor version, 514 | but do not include claims that would be infringed only as a 515 | consequence of further modification of the contributor version. For 516 | purposes of this definition, ``control'' includes the right to grant 517 | patent sublicenses in a manner consistent with the requirements of 518 | this License. 519 | 520 | Each contributor grants you a non-exclusive, worldwide, royalty-free 521 | patent license under the contributor's essential patent claims, to 522 | make, use, sell, offer for sale, import and otherwise run, modify and 523 | propagate the contents of its contributor version. 524 | 525 | In the following three paragraphs, a ``patent license'' is any express 526 | agreement or commitment, however denominated, not to enforce a patent 527 | (such as an express permission to practice a patent or covenant not to 528 | sue for patent infringement). To ``grant'' such a patent license to a 529 | party means to make such an agreement or commitment not to enforce a 530 | patent against the party. 531 | 532 | If you convey a covered work, knowingly relying on a patent license, 533 | and the Corresponding Source of the work is not available for anyone 534 | to copy, free of charge and under the terms of this License, through a 535 | publicly available network server or other readily accessible means, 536 | then you must either (1) cause the Corresponding Source to be so 537 | available, or (2) arrange to deprive yourself of the benefit of the 538 | patent license for this particular work, or (3) arrange, in a manner 539 | consistent with the requirements of this License, to extend the patent 540 | license to downstream recipients. ``Knowingly relying'' means you have 541 | actual knowledge that, but for the patent license, your conveying the 542 | covered work in a country, or your recipient's use of the covered work 543 | in a country, would infringe one or more identifiable patents in that 544 | country that you have reason to believe are valid. 545 | 546 | If, pursuant to or in connection with a single transaction or 547 | arrangement, you convey, or propagate by procuring conveyance of, a 548 | covered work, and grant a patent license to some of the parties 549 | receiving the covered work authorizing them to use, propagate, modify 550 | or convey a specific copy of the covered work, then the patent license 551 | you grant is automatically extended to all recipients of the covered 552 | work and works based on it. 553 | 554 | A patent license is ``discriminatory'' if it does not include within the 555 | scope of its coverage, prohibits the exercise of, or is conditioned on 556 | the non-exercise of one or more of the rights that are specifically 557 | granted under this License. You may not convey a covered work if you 558 | are a party to an arrangement with a third party that is in the 559 | business of distributing software, under which you make payment to the 560 | third party based on the extent of your activity of conveying the 561 | work, and under which the third party grants, to any of the parties 562 | who would receive the covered work from you, a discriminatory patent 563 | license (a) in connection with copies of the covered work conveyed by 564 | you (or copies made from those copies), or (b) primarily for and in 565 | connection with specific products or compilations that contain the 566 | covered work, unless you entered into that arrangement, or that patent 567 | license was granted, prior to 28 March 2007. 568 | 569 | Nothing in this License shall be construed as excluding or limiting 570 | any implied license or other defenses to infringement that may 571 | otherwise be available to you under applicable patent law. 572 | 573 | @item No Surrender of Others' Freedom. 574 | 575 | If conditions are imposed on you (whether by court order, agreement or 576 | otherwise) that contradict the conditions of this License, they do not 577 | excuse you from the conditions of this License. If you cannot convey 578 | a covered work so as to satisfy simultaneously your obligations under 579 | this License and any other pertinent obligations, then as a 580 | consequence you may not convey it at all. For example, if you agree 581 | to terms that obligate you to collect a royalty for further conveying 582 | from those to whom you convey the Program, the only way you could 583 | satisfy both those terms and this License would be to refrain entirely 584 | from conveying the Program. 585 | 586 | @item Use with the GNU Affero General Public License. 587 | 588 | Notwithstanding any other provision of this License, you have 589 | permission to link or combine any covered work with a work licensed 590 | under version 3 of the GNU Affero General Public License into a single 591 | combined work, and to convey the resulting work. The terms of this 592 | License will continue to apply to the part which is the covered work, 593 | but the special requirements of the GNU Affero General Public License, 594 | section 13, concerning interaction through a network will apply to the 595 | combination as such. 596 | 597 | @item Revised Versions of this License. 598 | 599 | The Free Software Foundation may publish revised and/or new versions 600 | of the GNU General Public License from time to time. Such new 601 | versions will be similar in spirit to the present version, but may 602 | differ in detail to address new problems or concerns. 603 | 604 | Each version is given a distinguishing version number. If the Program 605 | specifies that a certain numbered version of the GNU General Public 606 | License ``or any later version'' applies to it, you have the option of 607 | following the terms and conditions either of that numbered version or 608 | of any later version published by the Free Software Foundation. If 609 | the Program does not specify a version number of the GNU General 610 | Public License, you may choose any version ever published by the Free 611 | Software Foundation. 612 | 613 | If the Program specifies that a proxy can decide which future versions 614 | of the GNU General Public License can be used, that proxy's public 615 | statement of acceptance of a version permanently authorizes you to 616 | choose that version for the Program. 617 | 618 | Later license versions may give you additional or different 619 | permissions. However, no additional obligations are imposed on any 620 | author or copyright holder as a result of your choosing to follow a 621 | later version. 622 | 623 | @item Disclaimer of Warranty. 624 | 625 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 626 | APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 627 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT 628 | WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT 629 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 630 | A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND 631 | PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE 632 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR 633 | CORRECTION. 634 | 635 | @item Limitation of Liability. 636 | 637 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 638 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR 639 | CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 640 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES 641 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT 642 | NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR 643 | LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM 644 | TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER 645 | PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 646 | 647 | @item Interpretation of Sections 15 and 16. 648 | 649 | If the disclaimer of warranty and limitation of liability provided 650 | above cannot be given local legal effect according to their terms, 651 | reviewing courts shall apply local law that most closely approximates 652 | an absolute waiver of all civil liability in connection with the 653 | Program, unless a warranty or assumption of liability accompanies a 654 | copy of the Program in return for a fee. 655 | 656 | @end enumerate 657 | 658 | @heading END OF TERMS AND CONDITIONS 659 | 660 | @heading How to Apply These Terms to Your New Programs 661 | 662 | If you develop a new program, and you want it to be of the greatest 663 | possible use to the public, the best way to achieve this is to make it 664 | free software which everyone can redistribute and change under these 665 | terms. 666 | 667 | To do so, attach the following notices to the program. It is safest 668 | to attach them to the start of each source file to most effectively 669 | state the exclusion of warranty; and each file should have at least 670 | the ``copyright'' line and a pointer to where the full notice is found. 671 | 672 | @smallexample 673 | @var{one line to give the program's name and a brief idea of what it does.} 674 | Copyright (C) @var{year} @var{name of author} 675 | 676 | This program is free software: you can redistribute it and/or modify 677 | it under the terms of the GNU General Public License as published by 678 | the Free Software Foundation, either version 3 of the License, or (at 679 | your option) any later version. 680 | 681 | This program is distributed in the hope that it will be useful, but 682 | WITHOUT ANY WARRANTY; without even the implied warranty of 683 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU 684 | General Public License for more details. 685 | 686 | You should have received a copy of the GNU General Public License 687 | along with this program. If not, see @url{https://www.gnu.org/licenses/}. 688 | @end smallexample 689 | 690 | Also add information on how to contact you by electronic and paper mail. 691 | 692 | If the program does terminal interaction, make it output a short 693 | notice like this when it starts in an interactive mode: 694 | 695 | @smallexample 696 | @var{program} Copyright (C) @var{year} @var{name of author} 697 | This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. 698 | This is free software, and you are welcome to redistribute it 699 | under certain conditions; type @samp{show c} for details. 700 | @end smallexample 701 | 702 | The hypothetical commands @samp{show w} and @samp{show c} should show 703 | the appropriate parts of the General Public License. Of course, your 704 | program's commands might be different; for a GUI interface, you would 705 | use an ``about box''. 706 | 707 | You should also get your employer (if you work as a programmer) or school, 708 | if any, to sign a ``copyright disclaimer'' for the program, if necessary. 709 | For more information on this, and how to apply and follow the GNU GPL, see 710 | @url{https://www.gnu.org/licenses/}. 711 | 712 | The GNU General Public License does not permit incorporating your 713 | program into proprietary programs. If your program is a subroutine 714 | library, you may consider it more useful to permit linking proprietary 715 | applications with the library. If this is what you want to do, use 716 | the GNU Lesser General Public License instead of this License. But 717 | first, please read @url{https://www.gnu.org/licenses/why-not-lgpl.html}. 718 | --------------------------------------------------------------------------------