[elpa] externals/dash 722fea6 033/439: Include docs in README

[Phillip Lord]

branch: externals/dash
commit 722fea60435847293aaca72021f158007c79ef79
Author: Magnar Sveen <address@hidden>
Commit: Magnar Sveen <address@hidden>

    Include docs in README
---
 README.md           |  140 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs.md             |  137 -------------------------------------------------
 examples-to-docs.el |   13 ++++-
 readme-postfix.md   |   20 +++++++
 readme-prefix.md    |   27 ++++++++++
 5 files changed, 197 insertions(+), 140 deletions(-)

diff --git a/README.md b/README.md
index 1f18676..129e4fd 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,146 @@ of course the original can also be written like
 
 which demonstrates the usefulness of both versions.
 
+## Documentation
+
+### !map `(fn list)`
+
+Returns a new list consisting of the result of applying `fn` to the items in 
`list`.
+
+```cl
+(!map (lambda (num) (* num num)) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
+(!map (quote square) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
+(!!map (* it it) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
+```
+
+### !reduce-from `(fn initial-value list)`
+
+Returns the result of applying `fn` to `initial-value` and the
+first item in `list`, then applying `fn` to that result and the 2nd
+item, etc. If `list` contains no items, returns `initial-value` and
+`fn` is not called.
+
+```cl
+(!reduce-from (quote +) 7 (quote (1 2))) ;; => 10
+(!reduce-from (lambda (memo item) (+ memo item)) 7 (quote (1 2))) ;; => 10
+(!!reduce-from (+ acc it) 7 (quote (1 2 3))) ;; => 13
+```
+
+### !reduce `(fn list)`
+
+Returns the result of applying `fn` to the first 2 items in `list`,
+then applying `fn` to that result and the 3rd item, etc. If `list`
+contains no items, `fn` must accept no arguments as well, and
+reduce returns the result of calling `fn` with no arguments. If
+`list` has only 1 item, it is returned and `fn` is not called.
+
+```cl
+(!reduce (quote +) (quote (1 2))) ;; => 3
+(!reduce (lambda (memo item) (format %s-%s memo item)) (quote (1 2 3))) ;; => 
1-2-3
+(!!reduce (format %s-%s acc it) (quote (1 2 3))) ;; => 1-2-3
+```
+
+### !filter `(fn list)`
+
+Returns a new list of the items in `list` for which `fn` returns a non-nil 
value.
+
+```cl
+(!filter (lambda (num) (= 0 (% num 2))) (quote (1 2 3 4))) ;; => (quote (2 4))
+(!filter (quote even?) (quote (1 2 3 4))) ;; => (quote (2 4))
+(!!filter (= 0 (% it 2)) (quote (1 2 3 4))) ;; => (quote (2 4))
+```
+
+### !remove `(fn list)`
+
+Returns a new list of the items in `list` for which `fn` returns nil.
+
+```cl
+(!remove (lambda (num) (= 0 (% num 2))) (quote (1 2 3 4))) ;; => (quote (1 3))
+(!remove (quote even?) (quote (1 2 3 4))) ;; => (quote (1 3))
+(!!remove (= 0 (% it 2)) (quote (1 2 3 4))) ;; => (quote (1 3))
+```
+
+### !concat `(&rest lists)`
+
+Returns a new list with the concatenation of the elements in
+the supplied `lists`.
+
+```cl
+(!concat (quote (1))) ;; => (quote (1))
+(!concat (quote (1)) (quote (2))) ;; => (quote (1 2))
+(!concat (quote (1)) (quote (2 3)) (quote (4))) ;; => (quote (1 2 3 4))
+```
+
+### !mapcat `(fn list)`
+
+Returns the result of applying concat to the result of applying map to `fn` 
and `list`.
+Thus function `fn` should return a collection.
+
+```cl
+(!mapcat (quote list) (quote (1 2 3))) ;; => (quote (1 2 3))
+(!mapcat (lambda (item) (list 0 item)) (quote (1 2 3))) ;; => (quote (0 1 0 2 
0 3))
+(!!mapcat (list 0 it) (quote (1 2 3))) ;; => (quote (0 1 0 2 0 3))
+```
+
+### !partial `(fn &rest args)`
+
+Takes a function `fn` and fewer than the normal arguments to `fn`,
+and returns a fn that takes a variable number of additional `args`.
+When called, the returned function calls `fn` with args +
+additional args.
+
+```cl
+(funcall (!partial (quote +) 5) 3) ;; => 8
+(funcall (!partial (quote +) 5 2) 3) ;; => 10
+```
+
+### !difference `(list list2)`
+
+Return a new list with only the members of `list` that are not in LIST2.
+The test for equality is done with `equal`,
+or with `!compare-fn` if that's non-nil.
+
+```cl
+(!difference (quote nil) (quote nil)) ;; => (quote nil)
+(!difference (quote (1 2 3)) (quote (4 5 6))) ;; => (quote (1 2 3))
+(!difference (quote (1 2 3 4)) (quote (3 4 5 6))) ;; => (quote (1 2))
+```
+
+### !intersection `(list list2)`
+
+Return a new list containing only the elements that are members of both `list` 
and LIST2.
+The test for equality is done with `equal`,
+or with `!compare-fn` if that's non-nil.
+
+```cl
+(!intersection (quote nil) (quote nil)) ;; => (quote nil)
+(!intersection (quote (1 2 3)) (quote (4 5 6))) ;; => (quote nil)
+(!intersection (quote (1 2 3 4)) (quote (3 4 5 6))) ;; => (quote (3 4))
+```
+
+### !uniq `(list)`
+
+Return a new list with all duplicates removed.
+The test for equality is done with `equal`,
+or with `!compare-fn` if that's non-nil.
+
+```cl
+(!uniq (quote nil)) ;; => (quote nil)
+(!uniq (quote (1 2 2 4))) ;; => (quote (1 2 4))
+```
+
+### !contains? `(list element)`
+
+Return whether `list` contains `element`.
+The test for equality is done with `equal`,
+or with `!compare-fn` if that's non-nil.
+
+```cl
+(!contains? (quote (1 2 3)) 1) ;; => t
+(!contains? (quote (1 2 3)) 2) ;; => t
+(!contains? (quote (1 2 3)) 4) ;; => nil
+```
+
 ## License
 
 Copyright (C) 2012 Magnar Sveen, Joel McCracken
diff --git a/docs.md b/docs.md
deleted file mode 100644
index a4762a0..0000000
--- a/docs.md
+++ /dev/null
@@ -1,137 +0,0 @@
-## !map `(fn list)`
-
-Returns a new list consisting of the result of applying `fn` to the items in 
`list`.
-
-```cl
-(!map (lambda (num) (* num num)) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
-(!map (quote square) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
-(!!map (* it it) (quote (1 2 3 4))) ;; => (quote (1 4 9 16))
-```
-
-## !reduce-from `(fn initial-value list)`
-
-Returns the result of applying `fn` to `initial-value` and the
-first item in `list`, then applying `fn` to that result and the 2nd
-item, etc. If `list` contains no items, returns `initial-value` and
-`fn` is not called.
-
-```cl
-(!reduce-from (quote +) 7 (quote (1 2))) ;; => 10
-(!reduce-from (lambda (memo item) (+ memo item)) 7 (quote (1 2))) ;; => 10
-(!!reduce-from (+ acc it) 7 (quote (1 2 3))) ;; => 13
-```
-
-## !reduce `(fn list)`
-
-Returns the result of applying `fn` to the first 2 items in `list`,
-then applying `fn` to that result and the 3rd item, etc. If `list`
-contains no items, `fn` must accept no arguments as well, and
-reduce returns the result of calling `fn` with no arguments. If
-`list` has only 1 item, it is returned and `fn` is not called.
-
-```cl
-(!reduce (quote +) (quote (1 2))) ;; => 3
-(!reduce (lambda (memo item) (format %s-%s memo item)) (quote (1 2 3))) ;; => 
1-2-3
-(!!reduce (format %s-%s acc it) (quote (1 2 3))) ;; => 1-2-3
-```
-
-## !filter `(fn list)`
-
-Returns a new list of the items in `list` for which `fn` returns a non-nil 
value.
-
-```cl
-(!filter (lambda (num) (= 0 (% num 2))) (quote (1 2 3 4))) ;; => (quote (2 4))
-(!filter (quote even?) (quote (1 2 3 4))) ;; => (quote (2 4))
-(!!filter (= 0 (% it 2)) (quote (1 2 3 4))) ;; => (quote (2 4))
-```
-
-## !remove `(fn list)`
-
-Returns a new list of the items in `list` for which `fn` returns nil.
-
-```cl
-(!remove (lambda (num) (= 0 (% num 2))) (quote (1 2 3 4))) ;; => (quote (1 3))
-(!remove (quote even?) (quote (1 2 3 4))) ;; => (quote (1 3))
-(!!remove (= 0 (% it 2)) (quote (1 2 3 4))) ;; => (quote (1 3))
-```
-
-## !concat `(&rest lists)`
-
-Returns a new list with the concatenation of the elements in
-the supplied `lists`.
-
-```cl
-(!concat (quote (1))) ;; => (quote (1))
-(!concat (quote (1)) (quote (2))) ;; => (quote (1 2))
-(!concat (quote (1)) (quote (2 3)) (quote (4))) ;; => (quote (1 2 3 4))
-```
-
-## !mapcat `(fn list)`
-
-Returns the result of applying concat to the result of applying map to `fn` 
and `list`.
-Thus function `fn` should return a collection.
-
-```cl
-(!mapcat (quote list) (quote (1 2 3))) ;; => (quote (1 2 3))
-(!mapcat (lambda (item) (list 0 item)) (quote (1 2 3))) ;; => (quote (0 1 0 2 
0 3))
-(!!mapcat (list 0 it) (quote (1 2 3))) ;; => (quote (0 1 0 2 0 3))
-```
-
-## !partial `(fn &rest args)`
-
-Takes a function `fn` and fewer than the normal arguments to `fn`,
-and returns a fn that takes a variable number of additional `args`.
-When called, the returned function calls `fn` with args +
-additional args.
-
-```cl
-(funcall (!partial (quote +) 5) 3) ;; => 8
-(funcall (!partial (quote +) 5 2) 3) ;; => 10
-```
-
-## !difference `(list list2)`
-
-Return a new list with only the members of `list` that are not in LIST2.
-The test for equality is done with `equal`,
-or with `!compare-fn` if that's non-nil.
-
-```cl
-(!difference (quote nil) (quote nil)) ;; => (quote nil)
-(!difference (quote (1 2 3)) (quote (4 5 6))) ;; => (quote (1 2 3))
-(!difference (quote (1 2 3 4)) (quote (3 4 5 6))) ;; => (quote (1 2))
-```
-
-## !intersection `(list list2)`
-
-Return a new list containing only the elements that are members of both `list` 
and LIST2.
-The test for equality is done with `equal`,
-or with `!compare-fn` if that's non-nil.
-
-```cl
-(!intersection (quote nil) (quote nil)) ;; => (quote nil)
-(!intersection (quote (1 2 3)) (quote (4 5 6))) ;; => (quote nil)
-(!intersection (quote (1 2 3 4)) (quote (3 4 5 6))) ;; => (quote (3 4))
-```
-
-## !uniq `(list)`
-
-Return a new list with all duplicates removed.
-The test for equality is done with `equal`,
-or with `!compare-fn` if that's non-nil.
-
-```cl
-(!uniq (quote nil)) ;; => (quote nil)
-(!uniq (quote (1 2 2 4))) ;; => (quote (1 2 4))
-```
-
-## !contains? `(list element)`
-
-Return whether `list` contains `element`.
-The test for equality is done with `equal`,
-or with `!compare-fn` if that's non-nil.
-
-```cl
-(!contains? (quote (1 2 3)) 1) ;; => t
-(!contains? (quote (1 2 3)) 2) ;; => t
-(!contains? (quote (1 2 3)) 4) ;; => nil
-```
diff --git a/examples-to-docs.el b/examples-to-docs.el
index 0ff201a..586977b 100644
--- a/examples-to-docs.el
+++ b/examples-to-docs.el
@@ -33,15 +33,22 @@
         (signature (cadr function))
         (docstring (quote-docstring (cadr (cdr function))))
         (examples (cadr (cddr function))))
-    (format "## %s `%s`\n\n%s\n\n```cl\n%s\n```\n"
+    (format "### %s `%s`\n\n%s\n\n```cl\n%s\n```\n"
             command-name
             signature
             docstring
             (mapconcat 'identity (three-first examples) "\n"))))
 
 (defun create-docs-file ()
-  (with-temp-file "./docs.md"
-    (insert (mapconcat 'function-to-md (nreverse functions) "\n"))))
+  (with-temp-file "./README.md"
+    (insert-file-contents-literally "./readme-prefix.md")
+    (goto-char (point-max))
+    (newline)
+    (insert "## Documentation")
+    (newline 2)
+    (insert (mapconcat 'function-to-md (nreverse functions) "\n"))
+    (newline)
+    (insert-file-contents-literally "./readme-postfix.md")))
 
 (defun three-first (list)
   (let (first)
diff --git a/readme-postfix.md b/readme-postfix.md
new file mode 100644
index 0000000..2134443
--- /dev/null
+++ b/readme-postfix.md
@@ -0,0 +1,20 @@
+## License
+
+Copyright (C) 2012 Magnar Sveen, Joel McCracken
+
+Authors: Magnar Sveen <address@hidden>
+         Joel McCracken
+Keywords: lists
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/readme-prefix.md b/readme-prefix.md
new file mode 100644
index 0000000..78f30bf
--- /dev/null
+++ b/readme-prefix.md
@@ -0,0 +1,27 @@
+# bang.el [![Build 
Status](https://secure.travis-ci.org/magnars/bang.el.png)](http://travis-ci.org/magnars/bang.el)
+
+The startings of a modern list api for Emacs. Does not require 'cl.
+
+We're looking to Clojure for naming and signatures.
+
+## Warning
+
+This is so much a work in progress that you should definitely not be using it 
yet.
+
+## Anaphoric functions
+
+While `!filter` takes a function to filter the list by, you can also use the
+anaphoric form with double bangs - which will then be executed with `it` 
exposed
+as the list item. Here's an example:
+
+    (!filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; normal version
+
+    (!!filter (= 0 (% it 2)) '(1 2 3 4)) ;; anaphoric version
+
+of course the original can also be written like
+
+    (defun even? (num) (= 0 (% num 2)))
+
+    (!filter even? '(1 2 3 4))
+
+which demonstrates the usefulness of both versions.