[elpa] externals/dash 788573e 206/439: Merge pull request #36 from Wilfred/master

[Phillip Lord]

branch: externals/dash
commit 788573e079bfc5e134962076137f7f5748e33d04
Merge: 8b17154 b0ff280
Author: Magnar Sveen <address@hidden>
Commit: Magnar Sveen <address@hidden>

    Merge pull request #36 from Wilfred/master
    
    Adding -first-item and -last-item. [magnars/dash.el#17]
---
 README.md               |   18 ++++++++++++++++++
 dash.el                 |    7 +++++++
 dev/examples-to-docs.el |   36 +++++++++++++++++++++++++-----------
 dev/examples.el         |    8 ++++++++
 4 files changed, 58 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 67e17b9..fd9ad52 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,8 @@ Or you can just dump `dash.el` in your load path somewhere.
 
 ## Functions
 
+* [-first-item](#-first-item-list) `(list)`
+* [-last-item](#-last-item-list) `(list)`
 * [-map](#-map-fn-list) `(fn list)`
 * [-reduce-from](#-reduce-from-fn-initial-value-list) `(fn initial-value list)`
 * [-reduce-r-from](#-reduce-r-from-fn-initial-value-list) `(fn initial-value 
list)`
@@ -111,6 +113,22 @@ which demonstrates the usefulness of both versions.
 
 ## Documentation and examples
 
+### -first-item `(list)`
+
+Returns the first item of `list`, or nil on an empty list.
+
+```cl
+(-first-item '(1 2 3)) ;; => 1
+```
+
+### -last-item `(list)`
+
+Returns the first item of `list`, or nil on an empty list.
+
+```cl
+(-last-item '(1 2 3)) ;; => 3
+```
+
 ### -map `(fn list)`
 
 Returns a new list consisting of the result of applying `fn` to the items in 
`list`.
diff --git a/dash.el b/dash.el
index dce2b15..0570e7f 100644
--- a/dash.el
+++ b/dash.el
@@ -27,6 +27,13 @@
 
 ;;; Code:
 
+(defalias '-first-item 'car
+  "Returns the first item of LIST, or nil on an empty list.")
+
+(defun -last-item (list)
+  "Returns the first item of LIST, or nil on an empty list."
+  (car (last list)))
+
 (defmacro !cons (car cdr)
   "Destructive: Sets CDR to the cons of CAR and CDR."
   `(setq ,cdr (cons ,car ,cdr)))
diff --git a/dev/examples-to-docs.el b/dev/examples-to-docs.el
index 4b40b38..a5be5d3 100644
--- a/dev/examples-to-docs.el
+++ b/dev/examples-to-docs.el
@@ -1,4 +1,5 @@
 (require 'dash)
+(require 'help-fns)
 
 (defvar functions '())
 
@@ -11,21 +12,34 @@
       (replace-regexp-in-string "\t" "\\t" it t t)
       (replace-regexp-in-string "\r" "\\r" it t t))))
 
-(defun docs--signature (cmd)
-  (if (eq 'macro (car cmd))
-      (nth 2 cmd)
-    (nth 1 cmd)))
-
-(defun docs--docstring (cmd)
-  (if (eq 'macro (car cmd))
-      (nth 3 cmd)
-    (nth 2 cmd)))
+(defun docs--signature (function)
+  "Given FUNCTION (a symbol), return its argument list.
+FUNCTION may reference an elisp function, alias, macro or a subr."
+  (let* ((function-value (indirect-function function))
+         (is-alias (eq function-value (symbol-function function)))
+         ;; if FUNCTION isn't an alias, function-symbol is simply FUNCTION
+         (function-symbol function))
+    
+    (when is-alias
+      ;; find the last symbol in the alias chain
+      (while (symbolp (symbol-function function-symbol))
+        (setq function-symbol (symbol-function function-symbol))))
+    
+    (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)
   `(add-to-list 'functions (list
                             ',cmd
-                            (docs--signature (symbol-function ',cmd))
-                            (docs--docstring (symbol-function ',cmd))
+                            (docs--signature ',cmd)
+                            (documentation ',cmd)
                             (-map 'example-to-string (-partition 3 
',examples)))))
 
 (defun quote-and-downcase (string)
diff --git a/dev/examples.el b/dev/examples.el
index b2fe1bf..28e50bf 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -9,6 +9,14 @@
 (defun square (num) (* num num))
 (defun three-letters () '("A" "B" "C"))
 
+(defexamples -first-item
+  (-first-item '(1 2 3)) => 1
+  (-first-item nil => nil))
+
+(defexamples -last-item
+  (-last-item '(1 2 3)) => 3
+  (-last-item nil => nil))
+
 (defexamples -map
   (-map (lambda (num) (* num num)) '(1 2 3 4)) => '(1 4 9 16)
   (-map 'square '(1 2 3 4)) => '(1 4 9 16)