maurice/snix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(wpcarro/emacs): Document list.el

Browse source 
- Add README.md
- Remove stale TODOs
- Rephrase some of the module docs

Change-Id: I14002836feeca4dd702350151b64600ea2a9125d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6042
Reviewed-by: wpcarro <wpcarro@gmail.com>
Autosubmit: wpcarro <wpcarro@gmail.com>
Tested-by: BuildkiteCI
This commit is contained in:
William Carroll 2022-08-05 12:35:22 -07:00 • committed by clbot
parent e5503751c4
commit 8670746109
2 changed files with 25 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

19
users/wpcarro/emacs/pkgs/list/README.md Normal file
View file

@ -0,0 +1,19 @@
# list.el
Functions for working with lists in Elisp.
## Wish List
Here are some additional functions that I'd like to support.
- **TODO**: delete_at/2
- **TODO**: flatten/1
- **TODO**: flatten/2
- **TODO**: foldl/3
- **TODO**: foldr/3
- **TODO**: insert_at/3
- **TODO**: pop_at/3
- **TODO**: replace_at/3
- **TODO**: starts_with?/2
- **TODO**: update_at/3
- **TODO**: zip/1

38
users/wpcarro/emacs/pkgs/list/list.el
View file

@ -6,45 +6,23 @@
;;; Commentary: ;;; Commentary:
;; Since I prefer having the `list-' namespace, I wrote this module to wrap many ;; Since I prefer having the `list-' namespace, I wrote this module to wrap many
;; of the functions that are defined in the the global namespace in ELisp. I ;; of the functions that are defined in the the global namespace in Elisp. I
;; sometimes forget the names of these functions, so it's nice for them to be ;; sometimes forget the names of these functions, so it's nice for them to be
;; organized like this. ;; organized like this.
;; ;;
;; Motivation: ;; Motivation:
;; Here are some examples of function names that I cannot tolerate: ;; Here are some examples of function names where I prefer more modern
;; alternatives:
;; - `car': Return the first element (i.e. "head") of a linked list ;; - `car': Return the first element (i.e. "head") of a linked list
;; - `cdr': Return the tail of a linked list ;; - `cdr': Return the tail of a linked list
;; As are most APIs for standard libraries that I write, this is heavily ;; As are most APIs for standard libraries that I write, this is influenced by
;; influenced by Elixir's standard library. ;; Elixir's standard library.
;;
;; Elixir's List library:
;; - ++/2
;; - --/2
;; - hd/1
;; - tl/1
;; - in/2
;; - length/1
;; ;;
;; Similar libraries: ;; Similar libraries:
;; - dash.el: Functional library that mimmicks Clojure. It is consumed herein. ;; - dash.el: Excellent and widely adopted library for working with lists.
;; - list-utils.el: Utility library that covers things that dash.el may not ;; - list-utils.el: Utility library that covers things that dash.el may not
;; cover. ;; cover.
;; stream.el: Elisp implementation of streams, "implemented as delayed
;; evaluation of cons cells."
;; TODO: Consider naming this file linked-list.el.
;; TODO: Support module-like macro that auto-namespaces functions.
;; TODO: Consider wrapping most data structures like linked-lists,
;; associative-lists, etc in a `cl-defstruct', so that the dispatching by type
;; can be nominal instead of duck-typing. I'm not sure if this is a good idea
;; or not. If I do this, I should provide isomorphisms to map between idiomatic
;; ways of working with Elisp data structures and my wrapped variants.
;; TODO: Are function aliases/synonyms even a good idea? Or do they just
;; bloat the API unnecessarily?
;;; Code: ;;; Code:
@ -159,10 +137,6 @@ Returns a new list without X. If X occurs more than once, only the first
(list--assert-instance xs) (list--assert-instance xs)
(seq-find p xs)) (seq-find p xs))
;; TODO: Support dedupe.
;; TODO: Should we call this unique? Or distinct?
;; TODO: Add tests.
(defun list-dedupe-adjacent (xs) (defun list-dedupe-adjacent (xs)
"Return XS without adjacent duplicates." "Return XS without adjacent duplicates."
(list-reverse (list-reverse