wilderjds
/
dash.el
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Use actual advertised function signature in README

Browse Source 
* dev/examples-to-docs.el (docs--signature): Remove function.
(dash--describe): New function using the same machinery as
describe-function to determine arglists and docstrings.
(defexamples): Use it instead of docs--signature.

* README.md: Regenerate.
master
Basil L. Contovounesios 5 years ago
parent 7fc72d9171
commit 2aeb4e4f35
No known key found for this signature in database
GPG Key ID: 205AB54A5D5D8CFF
2 changed files with 39 additions and 64 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 58
      README.md
  2. 45
      dev/examples-to-docs.el

58
README.md
Unescape View File

@ -121,7 +121,7 @@ new list.
* [-splice](#-splice-pred-fun-list) `(pred fun list)` * [-splice](#-splice-pred-fun-list) `(pred fun list)`
* [-splice-list](#-splice-list-pred-new-list-list) `(pred new-list list)` * [-splice-list](#-splice-list-pred-new-list-list) `(pred new-list list)`
* [-mapcat](#-mapcat-fn-list) `(fn list)` * [-mapcat](#-mapcat-fn-list) `(fn list)`
* [-copy](#-copy-arg) `(arg)` * [-copy](#-copy-list) `(list)`
### Sublist selection ### Sublist selection
@ -132,7 +132,7 @@ Functions returning a sublist of the original list.
* [-remove](#-remove-pred-list) `(pred list)` * [-remove](#-remove-pred-list) `(pred list)`
* [-remove-first](#-remove-first-pred-list) `(pred list)` * [-remove-first](#-remove-first-pred-list) `(pred list)`
* [-remove-last](#-remove-last-pred-list) `(pred list)` * [-remove-last](#-remove-last-pred-list) `(pred list)`
* [-remove-item](#-remove-item-arg1-arg2) `(arg1 arg2)` * [-remove-item](#-remove-item-item-list) `(item list)`
* [-non-nil](#-non-nil-list) `(list)` * [-non-nil](#-non-nil-list) `(list)`
* [-slice](#-slice-list-from-optional-to-step) `(list from &optional to step)` * [-slice](#-slice-list-from-optional-to-step) `(list from &optional to step)`
* [-take](#-take-n-list) `(n list)` * [-take](#-take-n-list) `(n list)`
@ -284,14 +284,14 @@ Other list functions not fit to be classified elsewhere.
* [-some](#-some-pred-list) `(pred list)` * [-some](#-some-pred-list) `(pred list)`
* [-last](#-last-pred-list) `(pred list)` * [-last](#-last-pred-list) `(pred list)`
* [-first-item](#-first-item-list) `(list)` * [-first-item](#-first-item-list) `(list)`
* [-second-item](#-second-item-arg1) `(arg1)` * [-second-item](#-second-item-list) `(list)`
* [-third-item](#-third-item-arg1) `(arg1)` * [-third-item](#-third-item-list) `(list)`
* [-fourth-item](#-fourth-item-list) `(list)` * [-fourth-item](#-fourth-item-list) `(list)`
* [-fifth-item](#-fifth-item-list) `(list)` * [-fifth-item](#-fifth-item-list) `(list)`
* [-last-item](#-last-item-list) `(list)` * [-last-item](#-last-item-list) `(list)`
* [-butlast](#-butlast-list) `(list)` * [-butlast](#-butlast-list) `(list)`
* [-sort](#-sort-comparator-list) `(comparator list)` * [-sort](#-sort-comparator-list) `(comparator list)`
* [-list](#-list-optional-arg-rest-args) `(&optional arg &rest args)` * [-list](#-list-arg) `(arg)`
* [-fix](#-fix-fn-list) `(fn list)` * [-fix](#-fix-fn-list) `(fn list)`
### Tree operations ### Tree operations
@ -324,14 +324,14 @@ Functions pretending lists are trees.
Convenient versions of `let` and `let*` constructs combined with flow control. Convenient versions of `let` and `let*` constructs combined with flow control.
* [-when-let](#-when-let-var-val-rest-body) `(var-val &rest body)` * [-when-let](#-when-let-var-val-rest-body) `((var val) &rest body)`
* [-when-let*](#-when-let-vars-vals-rest-body) `(vars-vals &rest body)` * [-when-let*](#-when-let-vars-vals-rest-body) `(vars-vals &rest body)`
* [-if-let](#-if-let-var-val-then-rest-else) `(var-val then &rest else)` * [-if-let](#-if-let-var-val-then-rest-else) `((var val) then &rest else)`
* [-if-let*](#-if-let-vars-vals-then-rest-else) `(vars-vals then &rest else)` * [-if-let*](#-if-let-vars-vals-then-rest-else) `(vars-vals then &rest else)`
* [-let](#-let-varlist-rest-body) `(varlist &rest body)` * [-let](#-let-varlist-rest-body) `(varlist &rest body)`
* [-let*](#-let-varlist-rest-body) `(varlist &rest body)` * [-let*](#-let-varlist-rest-body) `(varlist &rest body)`
* [-lambda](#-lambda-match-form-rest-body) `(match-form &rest body)` * [-lambda](#-lambda-match-form-rest-body) `(match-form &rest body)`
* [-setq](#-setq-rest-forms) `(&rest forms)` * [-setq](#-setq-match-form-val) `([match-form val] ...)`
### Side effects ### Side effects
@ -496,12 +496,10 @@ Thus function `fn` should return a list.
(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3) (--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
``` ```
#### -copy `(arg)` #### -copy `(list)`
Create a shallow copy of `list`. Create a shallow copy of `list`.
(fn `list`)
```el ```el
(-copy '(1 2 3)) ;; => '(1 2 3) (-copy '(1 2 3)) ;; => '(1 2 3)
(let ((a '(1 2 3))) (eq a (-copy a))) ;; => nil (let ((a '(1 2 3))) (eq a (-copy a))) ;; => nil
@ -548,7 +546,7 @@ original tail. If no item is removed, then the result is a
complete copy. complete copy.
Alias: `-reject-first`. Alias: `-reject-first`.
This function's anaphoric counterpart is `--remove-first`. This function's anaphoric counterpart is `--remove-first`.
See also [`-map-first`](#-map-first-pred-rep-list), [`-remove-item`](#-remove-item-arg1-arg2), and [`-remove-last`](#-remove-last-pred-list). See also [`-map-first`](#-map-first-pred-rep-list), [`-remove-item`](#-remove-item-item-list), and [`-remove-last`](#-remove-last-pred-list).
```el ```el
(-remove-first #'natnump '(-2 -1 0 1 2)) ;; => '(-2 -1 1 2) (-remove-first #'natnump '(-2 -1 0 1 2)) ;; => '(-2 -1 1 2)
@ -563,7 +561,7 @@ The result is a copy of `list` regardless of whether an element is
removed. removed.
Alias: `-reject-last`. Alias: `-reject-last`.
This function's anaphoric counterpart is `--remove-last`. This function's anaphoric counterpart is `--remove-last`.
See also [`-map-last`](#-map-last-pred-rep-list), [`-remove-item`](#-remove-item-arg1-arg2), and [`-remove-first`](#-remove-first-pred-list). See also [`-map-last`](#-map-last-pred-rep-list), [`-remove-item`](#-remove-item-item-list), and [`-remove-first`](#-remove-first-pred-list).
```el ```el
(-remove-last #'natnump '(1 3 5 4 7 8 10 -11)) ;; => '(1 3 5 4 7 8 -11) (-remove-last #'natnump '(1 3 5 4 7 8 10 -11)) ;; => '(1 3 5 4 7 8 -11)
@ -571,13 +569,11 @@ See also [`-map-last`](#-map-last-pred-rep-list), [`-remove-item`](#-remove-item
(--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10)) ;; => '(1 2 3 4 5 6 7 8 9) (--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10)) ;; => '(1 2 3 4 5 6 7 8 9)
``` ```
#### -remove-item `(arg1 arg2)` #### -remove-item `(item list)`
Return a copy of `list` with all occurrences of `item` removed. Return a copy of `list` with all occurrences of `item` removed.
The comparison is done with `equal`. The comparison is done with `equal`.
(fn `item` `list`)
```el ```el
(-remove-item 3 '(1 2 3 2 3 4 5 3)) ;; => '(1 2 2 4 5) (-remove-item 3 '(1 2 3 2 3 4 5 3)) ;; => '(1 2 2 4 5)
(-remove-item 'foo '(foo bar baz foo)) ;; => '(bar baz) (-remove-item 'foo '(foo bar baz foo)) ;; => '(bar baz)
@ -645,8 +641,6 @@ Return nil if `list` contains `n` items or fewer.
Return `list` if `n` is zero or less. Return `list` if `n` is zero or less.
For another variant, see also [`-drop-last`](#-drop-last-n-list). For another variant, see also [`-drop-last`](#-drop-last-n-list).
(fn `n` `list`)
```el ```el
(-drop 3 '(1 2 3 4 5)) ;; => '(4 5) (-drop 3 '(1 2 3 4 5)) ;; => '(4 5)
(-drop 17 '(1 2 3 4 5)) ;; => nil (-drop 17 '(1 2 3 4 5)) ;; => nil
@ -2007,9 +2001,7 @@ Return the last x in `list` where (`pred` x) is non-nil, else nil.
Return the first item of `list`, or nil on an empty list. Return the first item of `list`, or nil on an empty list.
See also: [`-second-item`](#-second-item-arg1), [`-last-item`](#-last-item-list). See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list).
(fn `list`)
```el ```el
(-first-item '(1 2 3)) ;; => 1 (-first-item '(1 2 3)) ;; => 1
@ -2017,27 +2009,23 @@ See also: [`-second-item`](#-second-item-arg1), [`-last-item`](#-last-item-list)
(let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => '(5 2 3) (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => '(5 2 3)
``` ```
#### -second-item `(arg1)` #### -second-item `(list)`
Return the second item of `list`, or nil if `list` is too short. Return the second item of `list`, or nil if `list` is too short.
See also: [`-third-item`](#-third-item-arg1). See also: [`-third-item`](#-third-item-list).
(fn `list`)
```el ```el
(-second-item '(1 2 3)) ;; => 2 (-second-item '(1 2 3)) ;; => 2
(-second-item nil) ;; => nil (-second-item nil) ;; => nil
``` ```
#### -third-item `(arg1)` #### -third-item `(list)`
Return the third item of `list`, or nil if `list` is too short. Return the third item of `list`, or nil if `list` is too short.
See also: [`-fourth-item`](#-fourth-item-list). See also: [`-fourth-item`](#-fourth-item-list).
(fn `list`)
```el ```el
(-third-item '(1 2 3)) ;; => 3 (-third-item '(1 2 3)) ;; => 3
(-third-item nil) ;; => nil (-third-item nil) ;; => nil
@ -2098,7 +2086,7 @@ if the first element should sort before the second.
(--sort (< it other) '(3 1 2)) ;; => '(1 2 3) (--sort (< it other) '(3 1 2)) ;; => '(1 2 3)
``` ```
#### -list `(&optional arg &rest args)` #### -list `(arg)`
Ensure `arg` is a list. Ensure `arg` is a list.
If `arg` is already a list, return it as is (not a copy). If `arg` is already a list, return it as is (not a copy).
@ -2361,14 +2349,12 @@ which `forms` may have modified by side effect.
Convenient versions of `let` and `let*` constructs combined with flow control. Convenient versions of `let` and `let*` constructs combined with flow control.
#### -when-let `(var-val &rest body)` #### -when-let `((var val) &rest body)`
If `val` evaluates to non-nil, bind it to `var` and execute body. If `val` evaluates to non-nil, bind it to `var` and execute body.
Note: binding is done according to [`-let`](#-let-varlist-rest-body). Note: binding is done according to [`-let`](#-let-varlist-rest-body).
(fn (`var` `val`) &rest `body`)
```el ```el
(-when-let (match-index (string-match "d" "abcd")) (+ match-index 2)) ;; => 5 (-when-let (match-index (string-match "d" "abcd")) (+ match-index 2)) ;; => 5
(-when-let ((&plist :foo foo) (list :foo "foo")) foo) ;; => "foo" (-when-let ((&plist :foo foo) (list :foo "foo")) foo) ;; => "foo"
@ -2390,15 +2376,13 @@ encountered.
(-when-let* ((x 5) (y nil) (z 7)) (+ x y z)) ;; => nil (-when-let* ((x 5) (y nil) (z 7)) (+ x y z)) ;; => nil
``` ```
#### -if-let `(var-val then &rest else)` #### -if-let `((var val) then &rest else)`
If `val` evaluates to non-nil, bind it to `var` and do `then`, If `val` evaluates to non-nil, bind it to `var` and do `then`,
otherwise do `else`. otherwise do `else`.
Note: binding is done according to [`-let`](#-let-varlist-rest-body). Note: binding is done according to [`-let`](#-let-varlist-rest-body).
(fn (`var` `val`) `then` &rest `else`)
```el ```el
(-if-let (match-index (string-match "d" "abc")) (+ match-index 3) 7) ;; => 7 (-if-let (match-index (string-match "d" "abc")) (+ match-index 3) 7) ;; => 7
(--if-let (even? 4) it nil) ;; => t (--if-let (even? 4) it nil) ;; => t
@ -2631,7 +2615,7 @@ See [`-let`](#-let-varlist-rest-body) for a description of the destructuring mec
(funcall (-lambda ((_ . a) (_ . b)) (-concat a b)) '(1 2 3) '(4 5 6)) ;; => '(2 3 5 6) (funcall (-lambda ((_ . a) (_ . b)) (-concat a b)) '(1 2 3) '(4 5 6)) ;; => '(2 3 5 6)
``` ```
#### -setq `(&rest forms)` #### -setq `([match-form val] ...)`
Bind each `match-form` to the value of its `val`. Bind each `match-form` to the value of its `val`.
@ -2652,8 +2636,6 @@ expands roughly speaking to the following code
Care is taken to only evaluate each `val` once so that in case of Care is taken to only evaluate each `val` once so that in case of
multiple assignments it does not cause unexpected side effects. multiple assignments it does not cause unexpected side effects.
(fn [`match-form` `val`]...)
```el ```el
(let (a) (-setq a 1) a) ;; => 1 (let (a) (-setq a 1) a) ;; => 1
(let (a b) (-setq (a b) (list 1 2)) (list a b)) ;; => '(1 2) (let (a b) (-setq (a b) (list 1 2)) (list a b)) ;; => '(1 2)

45
dev/examples-to-docs.el
Unescape View File

@ -23,6 +23,8 @@
(require 'dash) (require 'dash)
(require 'dash-functional) (require 'dash-functional)
(require 'help-fns)
(require 'lisp-mnt) (require 'lisp-mnt)
(setq text-quoting-style 'grave) (setq text-quoting-style 'grave)
@ -43,34 +45,25 @@
(lambda (s) (concat "\\" (text-char-description (string-to-char s)))) (lambda (s) (concat "\\" (text-char-description (string-to-char s))))
it t t)))) it t t))))
(defun docs--signature (function) (defun dash--describe (fn)
"Given FUNCTION (a symbol), return its argument list. "Return the (ARGLIST DOCSTRING) of FN symbol."
FUNCTION may reference an elisp function, alias, macro or a subr." (with-temp-buffer
(let* ((function-value (indirect-function function)) (pcase-let* ((`(,real-fn ,def ,_alias ,real-def)
(is-alias (not (eq function-value (symbol-function function)))) (help-fns--analyze-function fn))
;; if FUNCTION isn't an alias, function-symbol is simply FUNCTION (buf (current-buffer))
(function-symbol function)) (doc-raw (documentation fn t))
(doc (help-fns--signature fn doc-raw real-def real-fn buf)))
(when is-alias (goto-char (1+ (point-min)))
;; find the last symbol in the alias chain (delete-region (point) (progn (forward-sexp) (1+ (point))))
(while (symbolp (symbol-function function-symbol)) (downcase-region (point) (point-max))
(setq function-symbol (symbol-function function-symbol)))) (backward-char)
(list (read buf) doc))))
(if (subrp function-value)
;; read the docstring to find the signature for subrs
(let* ((docstring-args (car (help-split-fundoc
(documentation function-value)
function-symbol)))
(fun-with-args (read (downcase docstring-args))))
(cdr fun-with-args))
;; otherwise get the signature directly
(help-function-arglist function-symbol))))
(defmacro defexamples (cmd &rest examples) (defmacro defexamples (cmd &rest examples)
`(push (list ',cmd `(push (cons ',cmd
(docs--signature ',cmd) (nconc (dash--describe ',cmd)
(documentation ',cmd) (list (mapcar #'example-to-string
(mapcar #'example-to-string (-partition 3 ',examples))) (-partition 3 ',examples)))))
functions)) functions))
(defmacro def-example-group (group desc &rest examples) (defmacro def-example-group (group desc &rest examples)

Write Preview
Loading…
Cancel
Save