From 8670746109c9ee2fecb91581cd74d6c913770ae8 Mon Sep 17 00:00:00 2001 From: William Carroll Date: Fri, 5 Aug 2022 12:35:22 -0700 Subject: docs(wpcarro/emacs): Document list.el - 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 Autosubmit: wpcarro Tested-by: BuildkiteCI --- users/wpcarro/emacs/pkgs/list/README.md | 19 +++++++++++++++++ users/wpcarro/emacs/pkgs/list/list.el | 38 ++++++--------------------------- 2 files changed, 25 insertions(+), 32 deletions(-) create mode 100644 users/wpcarro/emacs/pkgs/list/README.md (limited to 'users/wpcarro/emacs/pkgs') diff --git a/users/wpcarro/emacs/pkgs/list/README.md b/users/wpcarro/emacs/pkgs/list/README.md new file mode 100644 index 000000000000..7afa8494fb7a --- /dev/null +++ b/users/wpcarro/emacs/pkgs/list/README.md @@ -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 diff --git a/users/wpcarro/emacs/pkgs/list/list.el b/users/wpcarro/emacs/pkgs/list/list.el index a395eba2672e..3196d85856c1 100644 --- a/users/wpcarro/emacs/pkgs/list/list.el +++ b/users/wpcarro/emacs/pkgs/list/list.el @@ -6,45 +6,23 @@ ;;; Commentary: ;; 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 ;; organized like this. ;; ;; 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 ;; - `cdr': Return the tail of a linked list -;; As are most APIs for standard libraries that I write, this is heavily -;; influenced by Elixir's standard library. -;; -;; Elixir's List library: -;; - ++/2 -;; - --/2 -;; - hd/1 -;; - tl/1 -;; - in/2 -;; - length/1 +;; As are most APIs for standard libraries that I write, this is influenced by +;; Elixir's standard library. ;; ;; 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 ;; 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: @@ -159,10 +137,6 @@ Returns a new list without X. If X occurs more than once, only the first (list--assert-instance xs) (seq-find p xs)) -;; TODO: Support dedupe. -;; TODO: Should we call this unique? Or distinct? - -;; TODO: Add tests. (defun list-dedupe-adjacent (xs) "Return XS without adjacent duplicates." (list-reverse -- cgit 1.4.1