(GitHub Action) Deprecate some aliases and prefer "sequence" to "seq" in built-in names. (#206)

This commit was copied from the master branch.

Commit: 38126cc
Author: okamsn <28612288+okamsn@users.noreply.github.com>
Date: 2024-09-04 01:34:27 +0000

Deprecate some aliases and prefer "sequence" to "seq" in built-in names. (#206)

- 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.

Author: github-actions[bot]

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
 

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.

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
@@ -2235,32 +2235,25 @@ same keywords as the =numbers= command ([[#numeric-iteration]]) for working with
 the index and choosing a range of the sequence elements through which to
 iterate.
 
+#+findex: sequence-index
+#+findex: sequencing-index
 #+findex: seq-index
-#+findex: seqi
 #+findex: seqing-index
-#+findex: sequencing-index
-#+findex: seqi
 #+findex: array-index
 #+findex: arraying-index
-#+findex: arrayi
 #+findex: list-index
 #+findex: listing-index
-#+findex: listi
 #+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=
+  - =sequencing-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
@@ -2290,7 +2283,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 +2296,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 +2358,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 +2393,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 +2427,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 alias =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
@@ -2491,17 +2479,16 @@ the accessed index during the loop.
            (finally-return map loopy-result))
   #+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
+#+findex: seq-ref
+#+findex: seqing-ref
+- =(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= and =seqing-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

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,22 +116,20 @@ 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
     ;; in "sum" and "summing".
     (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))