Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Deprecate some aliases. #206

Merged
merged 1 commit into from
Sep 4, 2024
Merged

Deprecate some aliases. #206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions README.org
View file
Open in desktop
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
71 changes: 29 additions & 42 deletions doc/loopy-doc.org
View file
Open in desktop
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 @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
71 changes: 43 additions & 28 deletions loopy-vars.el
View file
Open in desktop
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
Loading