Skip to content

Commit

Permalink
Deprecate some aliases.
Browse files Browse the repository at this point in the history 
- 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` and `sequence-ref` the default names in the code and the
  remaining places in the documentation.  This was already the case for most of
  the documentation.
  • Loading branch information
@okamsn
okamsn committed Sep 4, 2024
1 parent 455c14b commit b035892
Show file tree
Hide file tree
Showing 4 changed files with 90 additions and 63 deletions.
18 changes: 18 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,24 @@ 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. 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`
- `seq-ref`: `seqf`, `sequencef`, `sequencingf`, `elements-ref`


[#169]: https://github.com/okamsn/loopy/issues/169
[#203]: https://github.com/okamsn/loopy/pull/203
[#205]: https://github.com/okamsn/loopy/pull/205
Expand Down
4 changes: 4 additions & 0 deletions README.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
60 changes: 25 additions & 35 deletions doc/loopy-doc.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
71 changes: 43 additions & 28 deletions loopy-vars.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand All @@ -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))
Expand All @@ -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))
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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))

Expand Down

0 comments on commit b035892

Please sign in to comment.