ls.el -- List utilities for Emacs Lisp.

Provides a set of utilities for list processing in Emacs Lisp. Sister library to fn.el.

ls.el builds on the facilities provided by dash and cl and focuses on concision, readability and consistent naming conventions.

---

Installation

Place ls.el in any directory on your load-path and:

(require 'ls)

---

API

Note: initial and final sublists (those which form a contiguous sublist including the first or last element) are referred to as prefixes and suffixes, repectively, in this API.

List creation: ranges, list comprehensions, etc.

• ls-seq (from &optional to inc)
• ls-range (&rest clauses)

List access.

• ls-uncons (list)
• ls-last (list)

List modification.

• ls-cons-if-t (car cdr)
• ls-zero-when (pred list)
• ls-zero-unless (pred list)
• ls-reverse-sublist (start end list)

Sublists.

• ls-take-before (target-list)
• ls-take-to (target list)
• ls-drop-before (target list)
• ls-drop-to (target list)
• ls-take-until (pred list)
• ls-drop-until (pred list)
• ls-partition-by-indices (indices list)

Predicates.

• ls-proper? (list)
• ls-improper? (list)
• ls-proper-list? (object)
• ls-improper-list? (object)
• ls-sublist? (sub list)

---

List creation: ranges, list comprehensions, etc.

ls-seq (from &optional to inc)

Alias for number-sequence.

ls-range (&rest clauses)

Return a range of numbers (or other values) as a list.

The CLAUSES follow cl-loop syntax and an anaphoric loop variable i is exposed. This is equivalent to:

(cl-loop for i CLAUSES... collect i)

For more information on clauses, see Loop Facility

Examples:

(ls-range to 5)
;; (0 1 2 3 4 5)

(ls-range below 5)
;; (0 1 2 3 4)

(ls-range from 1 to 10 by 2)
;; (1 3 5 7 9)

(ls-range from 1 to 8 by 1.5)
;; (1 2.5 4.0 5.5 7.0)

(ls-range from 3 downto -3)
;; (3 2 1 0 -1 -2 -3)

(ls-range from 1 to 10 when (oddp i))
;; (1 3 5 7 9)

(ls-range from 1 until (> (* i i) 50))
;; (1 2 3 4 5 6 7)

(ls-range in '(a b c d e) by 'cddr)
;; (a c e)

(ls-range on '(a b c d))
;; ((a b c d) (b c d) (c d) (d))

(ls-range on (ls-range to 3))
;; ((0 1 2 3) (1 2 3) (2 3) (3))

(-map 'string (ls-range from ?A to ?K))
;; ("A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K")

---

List access.

ls-uncons (list)

Decompose LIST into car and cdr. If LIST is nil, return nil.

ls-last (list)

Return the last element of LIST.

---

List modification.

ls-cons-if-t (car cdr)

Create a new cons if CAR is non-nil, else return CDR.

(ls-cons-if-t 'a '(b c))
;; (a b c)
(ls-cons-if-t nil '(b c))
;; (b c)
(ls-cons-if-t 2 3)
;; (2 . 3)
(ls-cons-if-t nil 3)
;; 3

ls-zero-when (pred list)

Replace items where PRED yields t by zero in LIST.

(ls-zero-when (fn (zerop (mod <> 3))) (ls-range from 1 to 10))
;; (nil nil 3 nil nil 6 nil nil 9 nil)

ls-zero-unless (pred list)

Replace items where PRED yields nil by zero in LIST.

(ls-zero-unless (fn (zerop (mod <> 3))) (ls-range from 1 to 10))
;; (1 2 nil 4 5 nil 7 8 nil 10)

ls-reverse-sublist (start end list)

Return a copy of LIST with sublist [START, end) reversed.

(ls-reverse-sublist 3 7 (ls-seq 1 10))
;; (1 2 6 5 4 3 7 8 9 10)

---

Sublists.

ls-take-before (target list)

Return the sublist ending immediately before TARGET of LIST.
(deprecated alias: ls-take-before-elt)

ls-take-to (target list)

Return the sublist ending with TARGET of LIST.
(deprecated alias: ls-take-to-elt)

ls-drop-before (target list)

Return the sublist beginning with TARGET of LIST (alias for memql).
(deprecated alias: ls-drop-before-elt)

ls-drop-to (target list)

Return the sublist starting immediately after TARGET of LIST.
(deprecated alias: ls-drop-to-elt)

ls-take-until (pred list)

Return the prefix starting with the first argument for which PRED fails.

ls-drop-until (pred list)

Return the suffix starting with the first argument for which PRED fails.

Note that ls-take-until and ls-drop-until partition a list into two parts (the prefix before PRED first holds, and the rest).

ls-partition-by-indices (indices list)

Return a list of sublists partitioning LIST at INDICES.

INDICES may be in any order and should be in the range 0 < i < N. Out-of-range indices are ignored.

(ls-partition-by-indices '(1 3) (ls-seq 0 9))
;; ((0) (1 2) (3 4 5 6 7 8 9))

---

Predicates.

ls-proper? (list)

Return t if LIST is proper (ie. not dotted).

A proper list is one where each element is the car of a cons cell. nil is trivially a proper list.

If the argument is not a list, an error is thrown.

ls-improper? (list)

Return t if LIST is an improper (ie. dotted) list.

An improper list is one where the last element is the cdr of a cons cell (with the second-last element being the car). It is represented by dotted notation.

If the argument is not a list, an error is thrown.

ls-improper-list? (object)

Return t if OBJECT is a proper list.

fn-proper-list? (object)

Return t if OBJECT is an improper list.

ls-sublist? (sub list)

Return t if SUB is a contiguous sublist of LIST.

TODO

• ls-range:
  • Allow final collect clause (over-riding default of collect i). This permits map functionality, completing list comprehension syntax.
  • Allow initial for clause permitting (a) custom iteration variable names; and (b) destructuring.
• ls-take, ls-drop -- DWIM macros allowing clauses to specify various criteria for choosing a prefix/suffix.