From 8151ca9977130e3230d2014f920842b442d9204c Mon Sep 17 00:00:00 2001 From: okamsn Date: Wed, 28 Aug 2024 13:23:34 -0400 Subject: [PATCH] Deprecate some aliases and prefer "sequence" to "seq" in built-in names. - To cut back on an over-abundance of choice and to simplify documentation, the following built-in aliases have been made obsolete. They can still be added manually via `loopy-defalias`. - `array`: `across` - `array-ref`: `arrayf`, `arrayingf`, `stringf`, `stringingf`, `across-ref` - `cons`: `on` - `list`: `in` - `list-ref`: `listf`, `listingf`, `in-ref` - `map-ref`: `mapf`, `mappingf` - `numbers`: `num`, `nums` - `numbers-down`: `nums-down`, `numdown`, `num-down`, `numsdown` - `numbers-up`: `nums-up`, `numup`, `num-up`, `numsup` - `set-prev`: `prev` - `seq`: `elements` - `seq-index`: `sequencei`, `seqi`, `listi`, `arrayi`, `stringi` - Document the aliases `mapping-ref`, `listing-ref`, `arraying-ref`, `stringing-ref`, and `sequencing-ref`. - Make `sequence`, `sequence-ref`, `sequence-index` the default names in the code and the remaining places in the documentation. This was already the case for most of the documentation. See this PR #206 and issue #126. --- CHANGELOG.md | 27 ++++++++++++++++++ README.org | 4 +++ doc/loopy-doc.org | 60 +++++++++++++++++---------------------- loopy-vars.el | 71 ++++++++++++++++++++++++++++------------------- 4 files changed, 99 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b26fa39..0ebe60dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,9 +17,36 @@ This document describes the user-facing changes to Loopy. - Remove the deprecated positional arguments to the `numbers` command ([#205]). +- To cut back on an over-abundance of choice and to simplify documentation, the + following built-in aliases have been made obsolete ([#126], [#206]). They can + still be added manually via `loopy-defalias`. + - `array`: `across` + - `array-ref`: `arrayf`, `arrayingf`, `stringf`, `stringingf`, `across-ref` + - `cons`: `on` + - `list`: `in` + - `list-ref`: `listf`, `listingf`, `in-ref` + - `map-ref`: `mapf`, `mappingf` + - `numbers`: `num`, `nums` + - `numbers-down`: `nums-down`, `numdown`, `num-down`, `numsdown` + - `numbers-up`: `nums-up`, `numup`, `num-up`, `numsup` + - `set-prev`: `prev` + - `sequence`: `elements` + - `sequence-index`: `sequencei`, `seqi`, `listi`, `arrayi`, `stringi` + - `sequence-ref`: `seqf`, `sequencef`, `sequencingf`, `elements-ref` + +- Make `sequence` the default name and `seq` an alias ([#126, #206]). + +- Make `sequence-ref` the default name and `seq-ref` an alias ([#126, #206]). + +- Make `sequence-index` the default name and `seq-index` an alias ([#126, #206]). + + +[#126]: https://github.com/okamsn/loopy/issues/126 [#169]: https://github.com/okamsn/loopy/issues/169 [#203]: https://github.com/okamsn/loopy/pull/203 [#205]: https://github.com/okamsn/loopy/pull/205 +[#206]: https://github.com/okamsn/loopy/pull/206 + ## 0.13.0 diff --git a/README.org b/README.org index a606e467..2fe3b609 100644 --- a/README.org +++ b/README.org @@ -35,6 +35,10 @@ please let me know. a warning. In the future, they will signal an error. - The positional arguments to the =numbers= command have been removed, being deprecated since version 0.12.0. + - Some built-in aliases have been made obsolete and will be removed from the + list of built-in aliases in the future. They can still be added to the + list of known aliases using ~loopy-defalias~. See the changelog for more + information. - Version 0.13.0: - The deprecated =:init= keyword argument has been removed. Use the =with= special macro argument instead. diff --git a/doc/loopy-doc.org b/doc/loopy-doc.org index 8f41e818..5ee3bfa7 100644 --- a/doc/loopy-doc.org +++ b/doc/loopy-doc.org @@ -2080,7 +2080,7 @@ source sequences. library =seq.el=. #+end_quote - This command also has the aliases =seqing= and =sequencing=. + This command also has the aliases =sequencing= and =seqing=. =KEYS= is one or several of =from=, =upfrom=, =downfrom=, =to=, =upto=, =downto=, =above=, =below=, =by=, =test=, and =index=. =index= names the @@ -2249,19 +2249,16 @@ iterate. #+findex: string-index #+findex: stringing-index #+findex: stringi -- =(seq-index VAR EXPR &key KEYS)= :: Iterate through the indices of =EXPR=. +- =(sequence-index VAR EXPR &key KEYS)= :: Iterate through the indices of =EXPR=. There is only one implementation of this command; there are no type-specific versions. This command also has the following aliases: - - =array-index=, =arraying-index=, =arrayi= - - =list-index=, =listing-index=, =listi= - - =string-index=, =stringing-index=, =stringi= - - =sequence-index=, =sequenceing-index=, =sequencei=, =seqi=, =seqing-index= + - =array-index=, =arraying-index= + - =list-index=, =listing-index= + - =string-index=, =stringing-index= + - =sequenceing-index=, =seq-index=, =seqing-index= - The aliases =seqi=, =arrayi=, =listi=, and =stringi= are similar to the - aliases =seqf=, =arrayf=, =listf=, and =stringf= of the =seq-ref= command. - =KEYS= is one or several of =from=, =upfrom=, =downfrom=, =to=, =upto=, =downto=, =above=, =below=, =by=, and =test=. For their meaning, see the =numbers= command. This command is very similar to =numbers=, except that it @@ -2290,7 +2287,7 @@ iterate. #+begin_src emacs-lisp ;; => (0 1 2) - (loopy (seq-index i [1 2 3]) + (loopy (sequence-index i [1 2 3]) (collect i)) ;; => (0 1 2) @@ -2303,7 +2300,7 @@ iterate. ;; => (8 6 4 2) (loopy (with (my-seq [0 1 2 3 4 5 6 7 8 9 10])) - (seq-index idx my-seq :from 8 :downto 1 :by 2) + (sequence-index idx my-seq :from 8 :downto 1 :by 2) (collect (elt my-seq idx))) #+end_src @@ -2365,17 +2362,13 @@ they also have an =index= keyword, which names the variable used to store the accessed index during the loop. #+findex: array-ref -#+findex: arrayf #+findex: string-ref -#+findex: stringf #+findex: arraying-ref -#+findex: arrayingf #+findex: stringing-ref -#+findex: stringingf -#+findex: across-ref -- =(array-ref|arrayf|string-ref|stringf VAR EXPR &key KEYS)= :: Loop - through the elements of the array =EXPR=, binding =VAR= as a ~setf~-able - place. +- =(array-ref|string-ref VAR EXPR &key KEYS)= :: Loop through the elements of + the array =EXPR=, binding =VAR= as a ~setf~-able place. + + This command also has the aliases =arraying-ref= and =stringing-ref=. =KEYS= is one or several of =from=, =upfrom=, =downfrom=, =to=, =upto=, =downto=, =above=, =below=, =by=, and =index=. =index= names the variable @@ -2404,12 +2397,11 @@ the accessed index during the loop. #+findex: list-ref #+findex: listing-ref -#+findex: listf -#+findex: listingf -#+findex: in-ref -- =(list-ref|listf VAR EXPR &key by)= :: Loop through the elements of - the list =EXPR=, binding =VAR= as a ~setf~-able place. Optionally, update - the list via function =by= instead of ~cdr~. +- =(list-ref VAR EXPR &key by)= :: Loop through the elements of the list =EXPR=, + binding =VAR= as a ~setf~-able place. Optionally, update the list via + function =by= instead of ~cdr~. + + This command also has the aliases =listing-ref=. #+BEGIN_SRC emacs-lisp ;; => (7 7 7) @@ -2439,11 +2431,11 @@ the accessed index during the loop. #+findex: map-ref #+findex: mapping-ref -#+findex: mapf -#+findex: mappingf -- =(map-ref|mapf VAR EXPR &key key unique)= :: Loop through the values of - map =EXPR=, binding =VAR= as a ~setf~-able place. Like the command =map=, - this command uses the =map.el= library. +- =(map-ref VAR EXPR &key key unique)= :: Loop through the values of map =EXPR=, + binding =VAR= as a ~setf~-able place. Like the command =map=, this command + uses the =map.el= library. + + This command also has the aliases =mapping-ref=. =key= is a variable in which to store the current key for the ~setf~-able place referred to by =VAR=. This is similar to the =index= keyword parameter @@ -2492,16 +2484,14 @@ the accessed index during the loop. #+end_src #+findex: seq-ref -#+findex: seqf #+findex: sequence-ref #+findex: sequencing-ref -#+findex: sequencef -#+findex: sequencingf -#+findex: elements-ref -- =(sequence-ref|sequencef|seq-ref|seqf VAR EXPR &key KEYS)= :: Loop +- =(sequence-ref|seq-ref VAR EXPR &key KEYS)= :: Loop through the elements of the sequence =EXPR=, binding =VAR= as a ~setf~-able place. + This command also has the aliases =sequencing-ref=. + =KEYS= is one or several of =from=, =upfrom=, =downfrom=, =to=, =upto=, =downto=, =above=, =below=, =by=, =test=, and =index=. =index= names the variable used to store the index being accessed. For others, see the diff --git a/loopy-vars.el b/loopy-vars.el index 3f298c37..0153ff37 100644 --- a/loopy-vars.el +++ b/loopy-vars.el @@ -74,26 +74,39 @@ Definition must exist. Neither argument need be quoted." ;; Add the alias for the new target name. (push alias (map-elt loopy-aliases true-name))))))) +(defvar loopy--obsolete-aliases + '((array across) + (array-ref arrayf arrayingf stringf stringingf across-ref) + (cons on) + (list in) + (list-ref listf listingf in-ref) + (map-ref mapf mappingf) + (numbers num nums) + (numbers-down nums-down numdown num-down numsdown) + (numbers-up nums-up numup num-up numsup) + (set-prev prev) + (sequence elements) + (sequence-index sequencei seqi listi arrayi stringi) + (sequence-ref seqf sequencef sequencingf elements-ref)) + "Aliases to be removed from the documentation.") + ;;;###autoload (defcustom loopy-aliases ;; TODO: Is there a faster way to search for aliases? ;; Would using a hash table with a flatter structure be better? ;; Using `map-do' on a hash table seemed to be a bit slower for what ;; we want? - '((accumulate . (callf2 accumulating)) + '((accumulate . (accumulating callf2)) (adjoin . (adjoining)) (after-do . (else after else-do)) (append . (appending)) - (array . (arraying string stringing across)) - (array-ref . ( arraying-ref arrayf arrayingf - stringf stringingf - string-ref stringing-ref - across-ref)) + (array . (arraying string stringing)) + (array-ref . (arraying-ref string-ref stringing-ref)) (at . (atting)) (before-do . (initially-do initially before)) (collect . (collecting)) (concat . (concating)) - (cons . (conses consing on)) + (cons . (conses consing)) (count . (counting)) (cycle . (cycling repeat repeating)) (finally-do . (finally)) @@ -103,10 +116,10 @@ Definition must exist. Neither argument need be quoted." (iter . (iterating)) (leave . (leaving)) (leave-from . (leaving-from)) - (list . (listing each in)) - (list-ref . (listf listingf listing-ref in-ref)) + (list . (listing each)) + (list-ref . (listing-ref)) (map . (mapping map-pairs mapping-pairs)) - (map-ref . (mapf mappingf mapping-ref)) + (map-ref . (mapping-ref)) (max . (maximizing maximize maxing)) ;; Unlike "maxing", there doesn't seem to be much on-line about the word ;; "minning", but the double-N follows conventional spelling rules, such as @@ -114,11 +127,9 @@ Definition must exist. Neither argument need be quoted." (min . (minimizing minimize minning)) (multiply . (multiplying)) (nconc . (nconcing)) - (numbers . (num nums number numbering)) - (numbers-down . ( nums-down numdown number-down num-down numsdown - numbering-down)) - (numbers-up . ( nums-up numup number-up num-up numsup - numbering-up)) + (numbers . (number numbering)) + (numbers-down . (number-down numbering-down)) + (numbers-up . (number-up numbering-up)) (nunion . (nunioning)) (opt-accum . (accum-opt)) (prepend . (prepending)) @@ -128,16 +139,14 @@ Definition must exist. Neither argument need be quoted." (return-from . (returning-from)) (set . (setting exprs expr)) (set-accum . (setting-accum)) - (set-prev . (setting-prev prev prev-expr prev-set)) - (seq . (seqing sequence sequencing elements)) - (seq-index . ( sequence-index seqing-index sequencing-index - sequencing-index sequencei seqi list-index listing-index - listi array-index arraying-index arrayi - string-index stringing-index stringi)) - (seq-ref . ( seqf seqing-ref - sequencef sequencingf sequence-ref - sequencing-ref - elements-ref)) + (set-prev . (setting-prev prev-expr prev-set)) + (sequence . (sequencing seq seqing)) + (sequence-index . ( seq-index seqing-index + sequencing-index + list-index listing-index + array-index arraying-index + string-index stringing-index)) + (sequence-ref . (seqing-ref seq-ref sequencing-ref)) (skip . (skipping continue continuing)) (skip-from . (skipping-from continue-from continuing-from)) (stream . (streaming)) @@ -203,9 +212,9 @@ true names and lists of aliases. (reduce . loopy--parse-reduce-command) (return . loopy--parse-return-command) (return-from . loopy--parse-return-from-command) - (seq . loopy--parse-seq-command) - (seq-index . loopy--parse-seq-index-command) - (seq-ref . loopy--parse-seq-ref-command) + (sequence . loopy--parse-seq-command) + (sequence-index . loopy--parse-seq-index-command) + (sequence-ref . loopy--parse-seq-ref-command) (set . loopy--parse-set-command) (set-prev . loopy--parse-set-prev-command) (skip . loopy--parse-skip-command) @@ -781,6 +790,12 @@ This predicate checks for presence in the list (when (memq name v) (cl-return-from loopy--get-true-name k))) loopy-aliases) + (map-do (lambda (k v) + (when (memq name v) + (warn "`loopy': `%s' is an obsolete built-in alias of `%s'. It will be removed in the future. To add it as a custom alias, use `loopy-defalias'." + name k) + (cl-return-from loopy--get-true-name k))) + loopy--obsolete-aliases) nil) name))