merge from trunk

1 files changed, 203 insertions, 0 deletions

diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
new file mode 100644
index 00000000000..e6d451ac62e
--- /dev/null
+++ b/lisp/emacs-lisp/subr-x.el
@@ -0,0 +1,203 @@
+;;; subr-x.el --- extra Lisp functions  -*- lexical-binding:t -*-
+
+;; Copyright (C) 2013-2015 Free Software Foundation, Inc.
+
+;; Maintainer: emacs-devel@gnu.org
+;; Keywords: convenience
+;; Package: emacs
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs 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.
+
+;; GNU Emacs 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 GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Less commonly used functions that complement basic APIs, often implemented in
+;; C code (like hash-tables and strings), and are not eligible for inclusion
+;; in subr.el.
+
+;; Do not document these functions in the lispref.
+;; http://lists.gnu.org/archive/html/emacs-devel/2014-01/msg01006.html
+
+;;; Code:
+
+(require 'pcase)
+
+
+(defmacro internal--thread-argument (first? &rest forms)
+  "Internal implementation for `thread-first' and `thread-last'.
+When Argument FIRST? is non-nil argument is threaded first, else
+last.  FORMS are the expressions to be threaded."
+  (pcase forms
+    (`(,x (,f . ,args) . ,rest)
+     `(internal--thread-argument
+       ,first? ,(if first? `(,f ,x ,@args) `(,f ,@args ,x)) ,@rest))
+    (`(,x ,f . ,rest) `(internal--thread-argument ,first? (,f ,x) ,@rest))
+    (_ (car forms))))
+
+(defmacro thread-first (&rest forms)
+  "Thread FORMS elements as the first argument of their successor.
+Example:
+    (thread-first
+      5
+      (+ 20)
+      (/ 25)
+      -
+      (+ 40))
+Is equivalent to:
+    (+ (- (/ (+ 5 20) 25)) 40)
+Note how the single `-' got converted into a list before
+threading."
+  (declare (indent 1)
+           (debug (form &rest [&or symbolp (sexp &rest form)])))
+  `(internal--thread-argument t ,@forms))
+
+(defmacro thread-last (&rest forms)
+  "Thread FORMS elements as the last argument of their successor.
+Example:
+    (thread-last
+      5
+      (+ 20)
+      (/ 25)
+      -
+      (+ 40))
+Is equivalent to:
+    (+ 40 (- (/ 25 (+ 20 5))))
+Note how the single `-' got converted into a list before
+threading."
+  (declare (indent 1) (debug thread-first))
+  `(internal--thread-argument nil ,@forms))
+
+(defsubst internal--listify (elt)
+  "Wrap ELT in a list if it is not one."
+  (if (not (listp elt))
+      (list elt)
+    elt))
+
+(defsubst internal--check-binding (binding)
+  "Check BINDING is properly formed."
+  (when (> (length binding) 2)
+    (signal
+     'error
+     (cons "`let' bindings can have only one value-form" binding)))
+  binding)
+
+(defsubst internal--build-binding-value-form (binding prev-var)
+  "Build the conditional value form for BINDING using PREV-VAR."
+  `(,(car binding) (and ,prev-var ,(cadr binding))))
+
+(defun internal--build-binding (binding prev-var)
+  "Check and build a single BINDING with PREV-VAR."
+  (thread-first
+      binding
+    internal--listify
+    internal--check-binding
+    (internal--build-binding-value-form prev-var)))
+
+(defun internal--build-bindings (bindings)
+  "Check and build conditional value forms for BINDINGS."
+  (let ((prev-var t))
+    (mapcar (lambda (binding)
+              (let ((binding (internal--build-binding binding prev-var)))
+                (setq prev-var (car binding))
+                binding))
+            bindings)))
+
+(defmacro if-let (bindings then &rest else)
+  "Process BINDINGS and if all values are non-nil eval THEN, else ELSE.
+Argument BINDINGS is a list of tuples whose car is a symbol to be
+bound and (optionally) used in THEN, and its cadr is a sexp to be
+evalled to set symbol's value.  In the special case you only want
+to bind a single value, BINDINGS can just be a plain tuple."
+  (declare (indent 2)
+           (debug ([&or (&rest (symbolp form)) (symbolp form)] form body)))
+  (when (and (<= (length bindings) 2)
+             (not (listp (car bindings))))
+    ;; Adjust the single binding case
+    (setq bindings (list bindings)))
+  `(let* ,(internal--build-bindings bindings)
+     (if ,(car (internal--listify (car (last bindings))))
+         ,then
+       ,@else)))
+
+(defmacro when-let (bindings &rest body)
+  "Process BINDINGS and if all values are non-nil eval BODY.
+Argument BINDINGS is a list of tuples whose car is a symbol to be
+bound and (optionally) used in BODY, and its cadr is a sexp to be
+evalled to set symbol's value.  In the special case you only want
+to bind a single value, BINDINGS can just be a plain tuple."
+  (declare (indent 1) (debug if-let))
+  (list 'if-let bindings (macroexp-progn body)))
+
+(defsubst hash-table-empty-p (hash-table)
+  "Check whether HASH-TABLE is empty (has 0 elements)."
+  (zerop (hash-table-count hash-table)))
+
+(defsubst hash-table-keys (hash-table)
+  "Return a list of keys in HASH-TABLE."
+  (let ((keys '()))
+    (maphash (lambda (k _v) (push k keys)) hash-table)
+    keys))
+
+(defsubst hash-table-values (hash-table)
+  "Return a list of values in HASH-TABLE."
+  (let ((values '()))
+    (maphash (lambda (_k v) (push v values)) hash-table)
+    values))
+
+(defsubst string-empty-p (string)
+  "Check whether STRING is empty."
+  (string= string ""))
+
+(defsubst string-join (strings &optional separator)
+  "Join all STRINGS using SEPARATOR."
+  (mapconcat 'identity strings separator))
+
+(define-obsolete-function-alias 'string-reverse 'reverse "25.1")
+
+(defsubst string-trim-left (string)
+  "Remove leading whitespace from STRING."
+  (if (string-match "\\`[ \t\n\r]+" string)
+      (replace-match "" t t string)
+    string))
+
+(defsubst string-trim-right (string)
+  "Remove trailing whitespace from STRING."
+  (if (string-match "[ \t\n\r]+\\'" string)
+      (replace-match "" t t string)
+    string))
+
+(defsubst string-trim (string)
+  "Remove leading and trailing whitespace from STRING."
+  (string-trim-left (string-trim-right string)))
+
+(defsubst string-blank-p (string)
+  "Check whether STRING is either empty or only whitespace."
+  (string-match-p "\\`[ \t\n\r]*\\'" string))
+
+(defsubst string-remove-prefix (prefix string)
+  "Remove PREFIX from STRING if present."
+  (if (string-prefix-p prefix string)
+      (substring string (length prefix))
+    string))
+
+(defsubst string-remove-suffix (suffix string)
+  "Remove SUFFIX from STRING if present."
+  (if (string-suffix-p suffix string)
+      (substring string 0 (- (length string) (length suffix)))
+    string))
+
+(provide 'subr-x)
+
+;;; subr-x.el ends here