From 5c86118b4ba818ed1fd48258f884f95d98674693 Mon Sep 17 00:00:00 2001 From: Phillip Lord Date: Mon, 26 Oct 2015 20:27:16 +0000 Subject: * lisp/emacs-lisp/ert.el: Print results without newline escaping --- lisp/emacs-lisp/ert.el | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el index 2eba0216faf..21c1f1be394 100644 --- a/lisp/emacs-lisp/ert.el +++ b/lisp/emacs-lisp/ert.el @@ -64,7 +64,7 @@ (require 'ewoc) (require 'find-func) (require 'help) - +(require 'pp) ;;; UI customization options. @@ -1300,7 +1300,8 @@ EXPECTEDP specifies whether the result was expected." (defun ert--pp-with-indentation-and-newline (object) "Pretty-print OBJECT, indenting it to the current column of point. Ensures a final newline is inserted." - (let ((begin (point))) + (let ((begin (point)) + (pp-escape-newlines nil)) (pp object (current-buffer)) (unless (bolp) (insert "\n")) (save-excursion -- cgit v1.2.1 From 7637849321a5bf3db8213ab23c38131a78e37dc9 Mon Sep 17 00:00:00 2001 From: Nicolas Petton Date: Mon, 26 Oct 2015 21:51:30 +0100 Subject: * lisp/emacs-lisp/seq.el: Rename all seq argumentss to sequence. --- lisp/emacs-lisp/seq.el | 306 ++++++++++++++++++++++++------------------------- 1 file changed, 153 insertions(+), 153 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el index f5189c7dc97..05e53783385 100644 --- a/lisp/emacs-lisp/seq.el +++ b/lisp/emacs-lisp/seq.el @@ -63,9 +63,9 @@ "Loop over a sequence. Similar to `dolist' but can be applied to lists, strings, and vectors. -Evaluate BODY with VAR bound to each element of SEQ, in turn. +Evaluate BODY with VAR bound to each element of SEQUENCE, in turn. -\(fn (VAR SEQ) BODY...)" +\(fn (VAR SEQUENCE) BODY...)" (declare (indent 1) (debug ((symbolp form &optional form) body))) `(seq-do (lambda (,(car spec)) ,@body) @@ -82,284 +82,284 @@ PATTERNS are given, and the match does not fail." `(and (pred seq-p) ,@(seq--make-pcase-bindings patterns))) -(defmacro seq-let (args seq &rest body) - "Bind the variables in ARGS to the elements of SEQ then evaluate BODY. +(defmacro seq-let (args sequence &rest body) + "Bind the variables in ARGS to the elements of SEQUENCE then evaluate BODY. ARGS can also include the `&rest' marker followed by a variable -name to be bound to the rest of SEQ." +name to be bound to the rest of SEQUENCE." (declare (indent 2) (debug t)) - `(pcase-let ((,(seq--make-pcase-patterns args) ,seq)) + `(pcase-let ((,(seq--make-pcase-patterns args) ,sequence)) ,@body)) -;;; Basic seq functions that have to be implemented by new seq types -(cl-defgeneric seq-elt (seq n) - "Return the element of SEQ at index N." - (elt seq n)) +;;; Basic seq functions that have to be implemented by new sequence types +(cl-defgeneric seq-elt (sequence n) + "Return the element of SEQUENCE at index N." + (elt sequence n)) ;; Default gv setters for `seq-elt'. ;; It can be a good idea for new sequence implementations to provide a ;; "gv-setter" for `seq-elt'. -(cl-defmethod (setf seq-elt) (store (seq array) n) - (aset seq n store)) +(cl-defmethod (setf seq-elt) (store (sequence array) n) + (aset sequence n store)) -(cl-defmethod (setf seq-elt) (store (seq cons) n) - (setcar (nthcdr n seq) store)) +(cl-defmethod (setf seq-elt) (store (sequence cons) n) + (setcar (nthcdr n sequence) store)) -(cl-defgeneric seq-length (seq) - "Return the length of the sequence SEQ." - (length seq)) +(cl-defgeneric seq-length (sequence) + "Return the length of SEQUENCE." + (length sequence)) -(cl-defgeneric seq-do (function seq) - "Apply FUNCTION to each element of SEQ, presumably for side effects. -Return SEQ." - (mapc function seq)) +(cl-defgeneric seq-do (function sequence) + "Apply FUNCTION to each element of SEQUENCE, presumably for side effects. +Return SEQUENCE." + (mapc function sequence)) (defalias 'seq-each #'seq-do) -(cl-defgeneric seq-p (seq) - "Return non-nil if SEQ is a sequence, nil otherwise." - (sequencep seq)) +(cl-defgeneric seq-p (sequence) + "Return non-nil if SEQUENCE is a sequence, nil otherwise." + (sequencep sequence)) -(cl-defgeneric seq-copy (seq) - "Return a shallow copy of SEQ." - (copy-sequence seq)) +(cl-defgeneric seq-copy (sequence) + "Return a shallow copy of SEQUENCE." + (copy-sequence sequence)) -(cl-defgeneric seq-subseq (seq start &optional end) - "Return the subsequence of SEQ from START to END. +(cl-defgeneric seq-subseq (sequence start &optional end) + "Return the subsequence of SEQUENCE from START to END. If END is omitted, it defaults to the length of the sequence. If START or END is negative, it counts from the end. Signal an error if START or END are outside of the sequence (i.e too large if positive or too small if negative)." - (cl-subseq seq start end)) + (cl-subseq sequence start end)) -(cl-defgeneric seq-map (function seq) - "Return the result of applying FUNCTION to each element of SEQ." +(cl-defgeneric seq-map (function sequence) + "Return the result of applying FUNCTION to each element of SEQUENCE." (let (result) (seq-do (lambda (elt) (push (funcall function elt) result)) - seq) + sequence) (nreverse result))) ;; faster implementation for sequences (sequencep) -(cl-defmethod seq-map (function (seq sequence)) - (mapcar function seq)) +(cl-defmethod seq-map (function (sequence sequence)) + (mapcar function sequence)) -(cl-defgeneric seq-drop (seq n) - "Return a subsequence of SEQ without its first N elements. -The result is a sequence of the same type as SEQ. +(cl-defgeneric seq-drop (sequence n) + "Return a subsequence of SEQUENCE without its first N elements. +The result is a sequence of the same type as SEQUENCE. -If N is a negative integer or zero, SEQ is returned." +If N is a negative integer or zero, SEQUENCE is returned." (if (<= n 0) - seq - (let ((length (seq-length seq))) - (seq-subseq seq (min n length) length)))) + sequence + (let ((length (seq-length sequence))) + (seq-subseq sequence (min n length) length)))) -(cl-defgeneric seq-take (seq n) - "Return a subsequence of SEQ with its first N elements. -The result is a sequence of the same type as SEQ. +(cl-defgeneric seq-take (sequence n) + "Return a subsequence of SEQUENCE with its first N elements. +The result is a sequence of the same type as SEQUENCE. If N is a negative integer or zero, an empty sequence is returned." - (seq-subseq seq 0 (min (max n 0) (seq-length seq)))) + (seq-subseq sequence 0 (min (max n 0) (seq-length sequence)))) -(cl-defgeneric seq-drop-while (pred seq) - "Return a sequence from the first element for which (PRED element) is nil in SEQ. -The result is a sequence of the same type as SEQ." - (seq-drop seq (seq--count-successive pred seq))) +(cl-defgeneric seq-drop-while (pred sequence) + "Return a sequence from the first element for which (PRED element) is nil in SEQUENCE. +The result is a sequence of the same type as SEQUENCE." + (seq-drop sequence (seq--count-successive pred sequence))) -(cl-defgeneric seq-take-while (pred seq) - "Return the successive elements for which (PRED element) is non-nil in SEQ. -The result is a sequence of the same type as SEQ." - (seq-take seq (seq--count-successive pred seq))) +(cl-defgeneric seq-take-while (pred sequence) + "Return the successive elements for which (PRED element) is non-nil in SEQUENCE. +The result is a sequence of the same type as SEQUENCE." + (seq-take sequence (seq--count-successive pred sequence))) -(cl-defgeneric seq-empty-p (seq) - "Return non-nil if the sequence SEQ is empty, nil otherwise." - (= 0 (seq-length seq))) +(cl-defgeneric seq-empty-p (sequence) + "Return non-nil if the SEQUENCE is empty, nil otherwise." + (= 0 (seq-length sequence))) -(cl-defgeneric seq-sort (pred seq) - "Return a sorted sequence comparing using PRED the elements of SEQ. -The result is a sequence of the same type as SEQ." - (let ((result (seq-sort pred (append seq nil)))) - (seq-into result (type-of seq)))) +(cl-defgeneric seq-sort (pred sequence) + "Return a sorted sequence comparing using PRED the elements of SEQUENCE. +The result is a sequence of the same type as SEQUENCE." + (let ((result (seq-sort pred (append sequence nil)))) + (seq-into result (type-of sequence)))) (cl-defmethod seq-sort (pred (list list)) (sort (seq-copy list) pred)) -(cl-defgeneric seq-reverse (seq) - "Return the reversed shallow copy of SEQ." +(cl-defgeneric seq-reverse (sequence) + "Return the reversed shallow copy of SEQUENCE." (let ((result '())) (seq-map (lambda (elt) (push elt result)) - seq) - (seq-into result (type-of seq)))) + sequence) + (seq-into result (type-of sequence)))) ;; faster implementation for sequences (sequencep) -(cl-defmethod seq-reverse ((seq sequence)) - (reverse seq)) +(cl-defmethod seq-reverse ((sequence sequence)) + (reverse sequence)) -(cl-defgeneric seq-concatenate (type &rest seqs) - "Concatenate, into a sequence of type TYPE, the sequences SEQS. +(cl-defgeneric seq-concatenate (type &rest sequences) + "Concatenate, into a sequence of type TYPE, the sequences SEQUENCES. TYPE must be one of following symbols: vector, string or list. \n(fn TYPE SEQUENCE...)" - (apply #'cl-concatenate type (seq-map #'seq-into-sequence seqs))) + (apply #'cl-concatenate type (seq-map #'seq-into-sequence sequences))) -(cl-defgeneric seq-into-sequence (seq) - "Convert SEQ into a sequence. +(cl-defgeneric seq-into-sequence (sequence) + "Convert SEQUENCE into a sequence. -The default implementation is to signal an error if SEQ is not a +The default implementation is to signal an error if SEQUENCE is not a sequence, specific functions should be implemented for new types -of seq." - (unless (sequencep seq) - (error "Cannot convert %S into a sequence" seq)) - seq) +of sequence." + (unless (sequencep sequence) + (error "Cannot convert %S into a sequence" sequence)) + sequence) -(cl-defgeneric seq-into (seq type) - "Convert the sequence SEQ into a sequence of type TYPE. +(cl-defgeneric seq-into (sequence type) + "Convert SEQUENCE into a sequence of type TYPE. TYPE can be one of the following symbols: vector, string or list." (pcase type - (`vector (vconcat seq)) - (`string (concat seq)) - (`list (append seq nil)) + (`vector (vconcat sequence)) + (`string (concat sequence)) + (`list (append sequence nil)) (_ (error "Not a sequence type name: %S" type)))) -(cl-defgeneric seq-filter (pred seq) - "Return a list of all the elements for which (PRED element) is non-nil in SEQ." +(cl-defgeneric seq-filter (pred sequence) + "Return a list of all the elements for which (PRED element) is non-nil in SEQUENCE." (let ((exclude (make-symbol "exclude"))) (delq exclude (seq-map (lambda (elt) (if (funcall pred elt) elt exclude)) - seq)))) + sequence)))) -(cl-defgeneric seq-remove (pred seq) - "Return a list of all the elements for which (PRED element) is nil in SEQ." +(cl-defgeneric seq-remove (pred sequence) + "Return a list of all the elements for which (PRED element) is nil in SEQUENCE." (seq-filter (lambda (elt) (not (funcall pred elt))) - seq)) + sequence)) -(cl-defgeneric seq-reduce (function seq initial-value) - "Reduce the function FUNCTION across SEQ, starting with INITIAL-VALUE. +(cl-defgeneric seq-reduce (function sequence initial-value) + "Reduce the function FUNCTION across SEQUENCE, starting with INITIAL-VALUE. Return the result of calling FUNCTION with INITIAL-VALUE and the -first element of SEQ, then calling FUNCTION with that result and -the second element of SEQ, then with that result and the third -element of SEQ, etc. +first element of SEQUENCE, then calling FUNCTION with that result and +the second element of SEQUENCE, then with that result and the third +element of SEQUENCE, etc. -If SEQ is empty, return INITIAL-VALUE and FUNCTION is not called." - (if (seq-empty-p seq) +If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called." + (if (seq-empty-p sequence) initial-value (let ((acc initial-value)) - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (setq acc (funcall function acc elt))) acc))) -(cl-defgeneric seq-every-p (pred seq) - "Return non-nil if (PRED element) is non-nil for all elements of the sequence SEQ." +(cl-defgeneric seq-every-p (pred sequence) + "Return non-nil if (PRED element) is non-nil for all elements of SEQUENCE." (catch 'seq--break - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (or (funcall pred elt) (throw 'seq--break nil))) t)) -(cl-defgeneric seq-some (pred seq) - "Return the first value for which if (PRED element) is non-nil for in SEQ." +(cl-defgeneric seq-some (pred sequence) + "Return the first value for which if (PRED element) is non-nil for in SEQUENCE." (catch 'seq--break - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (let ((result (funcall pred elt))) (when result (throw 'seq--break result)))) nil)) -(cl-defgeneric seq-find (pred seq &optional default) - "Return the first element for which (PRED element) is non-nil in SEQ. +(cl-defgeneric seq-find (pred sequence &optional default) + "Return the first element for which (PRED element) is non-nil in SEQUENCE. If no element is found, return DEFAULT. Note that `seq-find' has an ambiguity if the found element is identical to DEFAULT, as it cannot be known if an element was found or not." (catch 'seq--break - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (when (funcall pred elt) (throw 'seq--break elt))) default)) -(cl-defgeneric seq-count (pred seq) - "Return the number of elements for which (PRED element) is non-nil in SEQ." +(cl-defgeneric seq-count (pred sequence) + "Return the number of elements for which (PRED element) is non-nil in SEQUENCE." (let ((count 0)) - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (when (funcall pred elt) (setq count (+ 1 count)))) count)) -(cl-defgeneric seq-contains (seq elt &optional testfn) - "Return the first element in SEQ that is equal to ELT. +(cl-defgeneric seq-contains (sequence elt &optional testfn) + "Return the first element in SEQUENCE that is equal to ELT. Equality is defined by TESTFN if non-nil or by `equal' if nil." (seq-some (lambda (e) (funcall (or testfn #'equal) elt e)) - seq)) + sequence)) -(cl-defgeneric seq-position (seq elt &optional testfn) - "Return the index of the first element in SEQ that is equal to ELT. +(cl-defgeneric seq-position (sequence elt &optional testfn) + "Return the index of the first element in SEQUENCE that is equal to ELT. Equality is defined by TESTFN if non-nil or by `equal' if nil." (let ((index 0)) (catch 'seq--break - (seq-doseq (e seq) + (seq-doseq (e sequence) (when (funcall (or testfn #'equal) e elt) (throw 'seq--break index)) (setq index (1+ index))) nil))) -(cl-defgeneric seq-uniq (seq &optional testfn) - "Return a list of the elements of SEQ with duplicates removed. +(cl-defgeneric seq-uniq (sequence &optional testfn) + "Return a list of the elements of SEQUENCE with duplicates removed. TESTFN is used to compare elements, or `equal' if TESTFN is nil." (let ((result '())) - (seq-doseq (elt seq) + (seq-doseq (elt sequence) (unless (seq-contains result elt testfn) (setq result (cons elt result)))) (nreverse result))) -(cl-defgeneric seq-mapcat (function seq &optional type) - "Concatenate the result of applying FUNCTION to each element of SEQ. +(cl-defgeneric seq-mapcat (function sequence &optional type) + "Concatenate the result of applying FUNCTION to each element of SEQUENCE. The result is a sequence of type TYPE, or a list if TYPE is nil." (apply #'seq-concatenate (or type 'list) - (seq-map function seq))) + (seq-map function sequence))) -(cl-defgeneric seq-partition (seq n) - "Return a list of the elements of SEQ grouped into sub-sequences of length N. +(cl-defgeneric seq-partition (sequence n) + "Return a list of the elements of SEQUENCE grouped into sub-sequences of length N. The last sequence may contain less than N elements. If N is a negative integer or 0, nil is returned." (unless (< n 1) (let ((result '())) - (while (not (seq-empty-p seq)) - (push (seq-take seq n) result) - (setq seq (seq-drop seq n))) + (while (not (seq-empty-p sequence)) + (push (seq-take sequence n) result) + (setq sequence (seq-drop sequence n))) (nreverse result)))) -(cl-defgeneric seq-intersection (seq1 seq2 &optional testfn) - "Return a list of the elements that appear in both SEQ1 and SEQ2. +(cl-defgeneric seq-intersection (sequence1 sequence2 &optional testfn) + "Return a list of the elements that appear in both SEQUENCE1 and SEQUENCE2. Equality is defined by TESTFN if non-nil or by `equal' if nil." (seq-reduce (lambda (acc elt) - (if (seq-contains seq2 elt testfn) + (if (seq-contains sequence2 elt testfn) (cons elt acc) acc)) - (seq-reverse seq1) + (seq-reverse sequence1) '())) -(cl-defgeneric seq-difference (seq1 seq2 &optional testfn) - "Return a list of the elements that appear in SEQ1 but not in SEQ2. +(cl-defgeneric seq-difference (sequence1 sequence2 &optional testfn) + "Return a list of the elements that appear in SEQUENCE1 but not in SEQUENCE2. Equality is defined by TESTFN if non-nil or by `equal' if nil." (seq-reduce (lambda (acc elt) - (if (not (seq-contains seq2 elt testfn)) + (if (not (seq-contains sequence2 elt testfn)) (cons elt acc) acc)) - (seq-reverse seq1) + (seq-reverse sequence1) '())) -(cl-defgeneric seq-group-by (function seq) - "Apply FUNCTION to each element of SEQ. -Separate the elements of SEQ into an alist using the results as +(cl-defgeneric seq-group-by (function sequence) + "Apply FUNCTION to each element of SEQUENCE. +Separate the elements of SEQUENCE into an alist using the results as keys. Keys are compared using `equal'." (seq-reduce (lambda (acc elt) @@ -369,25 +369,25 @@ keys. Keys are compared using `equal'." (setcdr cell (push elt (cdr cell))) (push (list key elt) acc)) acc)) - (seq-reverse seq) + (seq-reverse sequence) nil)) -(cl-defgeneric seq-min (seq) - "Return the smallest element of SEQ. -SEQ must be a sequence of numbers or markers." - (apply #'min (seq-into seq 'list))) +(cl-defgeneric seq-min (sequence) + "Return the smallest element of SEQUENCE. +SEQUENCE must be a sequence of numbers or markers." + (apply #'min (seq-into sequence 'list))) -(cl-defgeneric seq-max (seq) - "Return the largest element of SEQ. -SEQ must be a sequence of numbers or markers." - (apply #'max (seq-into seq 'list))) +(cl-defgeneric seq-max (sequence) + "Return the largest element of SEQUENCE. +SEQUENCE must be a sequence of numbers or markers." + (apply #'max (seq-into sequence 'list))) -(defun seq--count-successive (pred seq) - "Return the number of successive elements for which (PRED element) is non-nil in SEQ." +(defun seq--count-successive (pred sequence) + "Return the number of successive elements for which (PRED element) is non-nil in SEQUENCE." (let ((n 0) - (len (seq-length seq))) + (len (seq-length sequence))) (while (and (< n len) - (funcall pred (seq-elt seq n))) + (funcall pred (seq-elt sequence n))) (setq n (+ 1 n))) n)) @@ -419,10 +419,10 @@ SEQ must be a sequence of numbers or markers." args))) ;; TODO: make public? -(defun seq--elt-safe (seq n) - "Return element of SEQ at the index N. +(defun seq--elt-safe (sequence n) + "Return element of SEQUENCE at the index N. If no element is found, return nil." - (ignore-errors (seq-elt seq n))) + (ignore-errors (seq-elt sequence n))) ;;; Optimized implementations for lists -- cgit v1.2.1 From 5a9842c933483716a92f2c4410ce58ca829a594f Mon Sep 17 00:00:00 2001 From: Nicolas Petton Date: Mon, 26 Oct 2015 22:16:27 +0100 Subject: * lisp/emacs-lisp/seq.el: Better docstrings. --- lisp/emacs-lisp/seq.el | 57 +++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 26 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el index 05e53783385..d0c2d24b015 100644 --- a/lisp/emacs-lisp/seq.el +++ b/lisp/emacs-lisp/seq.el @@ -61,10 +61,10 @@ (defmacro seq-doseq (spec &rest body) "Loop over a sequence. -Similar to `dolist' but can be applied to lists, strings, and vectors. - Evaluate BODY with VAR bound to each element of SEQUENCE, in turn. +Similar to `dolist' but can be applied to lists, strings, and vectors. + \(fn (VAR SEQUENCE) BODY...)" (declare (indent 1) (debug ((symbolp form &optional form) body))) `(seq-do (lambda (,(car spec)) @@ -72,18 +72,18 @@ Evaluate BODY with VAR bound to each element of SEQUENCE, in turn. ,(cadr spec))) (pcase-defmacro seq (&rest patterns) - "pcase pattern matching sequence elements. + "Build a `pcase' pattern that matches elements of SEQUENCE. -Matches if the object is a sequence (list, string or vector), and -each PATTERN matches the corresponding element of the sequence. +The `pcase' pattern will match each element of PATTERNS against the +corresponding element of SEQUENCE. -Supernumerary elements of the sequence are ignored if fewer -PATTERNS are given, and the match does not fail." +Extra elements of the sequence are ignored if fewer PATTERNS are +given, and the match does not fail." `(and (pred seq-p) ,@(seq--make-pcase-bindings patterns))) (defmacro seq-let (args sequence &rest body) - "Bind the variables in ARGS to the elements of SEQUENCE then evaluate BODY. + "Bind the variables in ARGS to the elements of SEQUENCE, then evaluate BODY. ARGS can also include the `&rest' marker followed by a variable name to be bound to the rest of SEQUENCE." @@ -94,7 +94,7 @@ name to be bound to the rest of SEQUENCE." ;;; Basic seq functions that have to be implemented by new sequence types (cl-defgeneric seq-elt (sequence n) - "Return the element of SEQUENCE at index N." + "Return Nth element of SEQUENCE." (elt sequence n)) ;; Default gv setters for `seq-elt'. @@ -107,7 +107,7 @@ name to be bound to the rest of SEQUENCE." (setcar (nthcdr n sequence) store)) (cl-defgeneric seq-length (sequence) - "Return the length of SEQUENCE." + "Return the number of elements of SEQUENCE." (length sequence)) (cl-defgeneric seq-do (function sequence) @@ -126,11 +126,13 @@ Return SEQUENCE." (copy-sequence sequence)) (cl-defgeneric seq-subseq (sequence start &optional end) - "Return the subsequence of SEQUENCE from START to END. -If END is omitted, it defaults to the length of the sequence. -If START or END is negative, it counts from the end. -Signal an error if START or END are outside of the sequence (i.e -too large if positive or too small if negative)." + "Return the sequence of elements of SEQUENCE from START to END. +END is inclusive. + +If END is omitted, it defaults to the length of the sequence. If +START or END is negative, it counts from the end. Signal an +error if START or END are outside of the sequence (i.e too large +if positive or too small if negative)." (cl-subseq sequence start end)) @@ -147,7 +149,7 @@ too large if positive or too small if negative)." (mapcar function sequence)) (cl-defgeneric seq-drop (sequence n) - "Return a subsequence of SEQUENCE without its first N elements. + "Remove the first N elements of SEQUENCE and return the result. The result is a sequence of the same type as SEQUENCE. If N is a negative integer or zero, SEQUENCE is returned." @@ -157,7 +159,7 @@ If N is a negative integer or zero, SEQUENCE is returned." (seq-subseq sequence (min n length) length)))) (cl-defgeneric seq-take (sequence n) - "Return a subsequence of SEQUENCE with its first N elements. + "Take the first N elements of SEQUENCE and return the result. The result is a sequence of the same type as SEQUENCE. If N is a negative integer or zero, an empty sequence is @@ -165,13 +167,15 @@ returned." (seq-subseq sequence 0 (min (max n 0) (seq-length sequence)))) (cl-defgeneric seq-drop-while (pred sequence) - "Return a sequence from the first element for which (PRED element) is nil in SEQUENCE. -The result is a sequence of the same type as SEQUENCE." + "Remove the successive elements of SEQUENCE for which PRED returns non-nil. +PRED is a function of one argument. The result is a sequence of +the same type as SEQUENCE." (seq-drop sequence (seq--count-successive pred sequence))) (cl-defgeneric seq-take-while (pred sequence) - "Return the successive elements for which (PRED element) is non-nil in SEQUENCE. -The result is a sequence of the same type as SEQUENCE." + "Take the successive elements of SEQUENCE for which PRED returns non-nil. +PRED is a function of one argument. The result is a sequence of +the same type as SEQUENCE." (seq-take sequence (seq--count-successive pred sequence))) (cl-defgeneric seq-empty-p (sequence) @@ -179,7 +183,7 @@ The result is a sequence of the same type as SEQUENCE." (= 0 (seq-length sequence))) (cl-defgeneric seq-sort (pred sequence) - "Return a sorted sequence comparing using PRED the elements of SEQUENCE. + "Sort SEQUENCE using PRED as comparison function. The result is a sequence of the same type as SEQUENCE." (let ((result (seq-sort pred (append sequence nil)))) (seq-into result (type-of sequence)))) @@ -188,7 +192,7 @@ The result is a sequence of the same type as SEQUENCE." (sort (seq-copy list) pred)) (cl-defgeneric seq-reverse (sequence) - "Return the reversed shallow copy of SEQUENCE." + "Return a sequence with elements of SEQUENCE in reverse order." (let ((result '())) (seq-map (lambda (elt) (push elt result)) @@ -200,7 +204,7 @@ The result is a sequence of the same type as SEQUENCE." (reverse sequence)) (cl-defgeneric seq-concatenate (type &rest sequences) - "Concatenate, into a sequence of type TYPE, the sequences SEQUENCES. + "Concatenate SEQUENCES into a single sequence of type TYPE. TYPE must be one of following symbols: vector, string or list. \n(fn TYPE SEQUENCE...)" @@ -217,8 +221,9 @@ of sequence." sequence) (cl-defgeneric seq-into (sequence type) - "Convert SEQUENCE into a sequence of type TYPE. -TYPE can be one of the following symbols: vector, string or list." + "Concatenate the elements of SEQUENCE into a sequence of type TYPE. +TYPE can be one of the following symbols: vector, string or +list." (pcase type (`vector (vconcat sequence)) (`string (concat sequence)) -- cgit v1.2.1 From 22579baf62fc5e6a4f0482172eb7a4e71d6fbcda Mon Sep 17 00:00:00 2001 From: Nicolas Petton Date: Mon, 26 Oct 2015 22:23:02 +0100 Subject: * lisp/emacs-lisp/map.el: Better docstrings. --- lisp/emacs-lisp/map.el | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el index cc437e02e78..5ef51f12d96 100644 --- a/lisp/emacs-lisp/map.el +++ b/lisp/emacs-lisp/map.el @@ -45,12 +45,12 @@ (require 'seq) (pcase-defmacro map (&rest args) - "pcase pattern matching map elements. + "Build a `pcase' pattern matching map elements. -Matches if the object is a map (list, hash-table or array), and -each PATTERN matches the corresponding elements of the map. +The `pcase' pattern will match each element of PATTERN against +the corresponding elements of the map. -Supernumerary elements of the map are ignored if fewer ARGS are +Extra elements of the map are ignored if fewer ARGS are given, and the match does not fail. ARGS can be a list of the form (KEY PAT), in which case KEY in an @@ -92,7 +92,7 @@ Return RESULT if non-nil or the result of evaluation of the form." (t (error "Unsupported map: %s" ,map-var))))) (defun map-elt (map key &optional default) - "Perform a lookup in MAP of KEY and return its associated value. + "Lookup KEY in MAP and return its associated value. If KEY is not found, return DEFAULT which defaults to nil. If MAP is a list, `eql' is used to lookup KEY. @@ -122,7 +122,7 @@ MAP can be a list, hash-table or array." default))) (defmacro map-put (map key value) - "In MAP, associate KEY with VALUE and return MAP. + "Associate KEY with VALUE in MAP and return MAP. If KEY is already present in MAP, replace the associated value with VALUE. @@ -133,8 +133,9 @@ MAP can be a list, hash-table or array." ,map))) (defmacro map-delete (map key) - "In MAP, delete the key KEY if present and return MAP. -If MAP is an array, store nil at the index KEY. + "Delete KEY from MAP and return MAP. +No error is signaled if KEY is not a key of MAP. If MAP is an +array, store nil at the index KEY. MAP can be a list, hash-table or array." (declare (debug t)) @@ -245,7 +246,7 @@ MAP can be a list, hash-table or array." (arrayp map))) (defun map-empty-p (map) - "Return non-nil is MAP is empty. + "Return non-nil if MAP is empty. MAP can be a list, hash-table or array." (map--dispatch map @@ -254,7 +255,7 @@ MAP can be a list, hash-table or array." :hash-table (zerop (hash-table-count map)))) (defun map-contains-key (map key &optional testfn) - "Return non-nil if MAP contain the key KEY, nil otherwise. + "Return non-nil if MAP contain KEY, nil otherwise. Equality is defined by TESTFN if non-nil or by `equal' if nil. MAP can be a list, hash-table or array." @@ -284,7 +285,7 @@ MAP can be a list, hash-table or array." t)) (defun map-merge (type &rest maps) - "Merge into a map of type TYPE all the key/value pairs in the maps MAPS. + "Merge into a map of type TYPE all the key/value pairs in MAPS. MAP can be a list, hash-table or array." (let (result) -- cgit v1.2.1 From 61b63f460ddfb443e2575e4fa7e7714b17579659 Mon Sep 17 00:00:00 2001 From: Nicolas Petton Date: Wed, 28 Oct 2015 09:54:00 +0100 Subject: * lisp/emacs-lisp/thunk.el (thunk-delay): Fix the macro. --- lisp/emacs-lisp/thunk.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/thunk.el b/lisp/emacs-lisp/thunk.el index d07b25736aa..0c5816a616d 100644 --- a/lisp/emacs-lisp/thunk.el +++ b/lisp/emacs-lisp/thunk.el @@ -57,8 +57,8 @@ ,forced (unless ,forced (setf ,val (progn ,@body)) - (setf ,forced t))) - ,val)))) + (setf ,forced t)) + ,val))))) (defun thunk-force (delayed) "Force the evaluation of DELAYED. -- cgit v1.2.1