branch: elpa/loopy
commit 7996ae466a321c1244903f2c579056d86a9db7a4
Author: okamsn <[email protected]>
Commit: GitHub <[email protected]>
Minor Org documentation fixes and improvements. (#264)
- Re-organize and improve `find` documentation.
- Split up and move examples into positions between paragraphs of further
detail.
- Note that when the `TEST` expression is a sharp-quoted function,
like in `#'cl-evenp`, that is treated like applying that function
to the value to be found.
- Fix documentation of example command `loopy--parse-if-command` in
the section Background Info. This example was
still using dotted pairs as instructions, when instructions are now
normal pairs.
Fixes #262.
---
doc/loopy-doc.org | 48 +++++++++++++++++++++++++++++++-----------------
doc/loopy.texi | 52 +++++++++++++++++++++++++++++++++-------------------
2 files changed, 64 insertions(+), 36 deletions(-)
diff --git a/doc/loopy-doc.org b/doc/loopy-doc.org
index c386645824b..9ac407f5d03 100644
--- a/doc/loopy-doc.org
+++ b/doc/loopy-doc.org
@@ -3648,13 +3648,6 @@ Sequence accumulation commands are used to join lists
(such as =union= and
This command also has the alias =finding=.
- If the loop is left early and =TEST= was never non-nil, this is the same as a
- normal failure and =VAR= will be set to the value of =ON-FAILURE=, if
- provided.
-
- To be consistent with other commands, =ON-FAILURE= is evaluated at the
- start of the loop, even though that is not necessarily where it is used.
-
#+BEGIN_SRC emacs-lisp
;; => (13 (1 2))
(loopy (list i '(1 2 3 4 5 6 7 8))
@@ -3670,15 +3663,37 @@ Sequence accumulation commands are used to join lists
(such as =union= and
(loopy (list i '(1 2 3 4 5 6))
(find i (> i 12) :on-failure 27))
- ;; => 27
- (loopy (list i '(1 2 3 4 5 6))
- (while (< i 3))
- (find i (> i 12) :on-failure 27))
-
;; => nil
(loopy (list i '(1 2 3 4 5 6))
(find nil (> i 3) :on-failure 27))
+ #+END_SRC
+
+ If the loop is left early and =TEST= was never non-nil, then this is the same
+ as a normal failure and =VAR= will be set to the value of =ON-FAILURE=, if
+ provided.
+
+ #+begin_src emacs-lisp
+ ;; => 27
+ (loopy (list i '(1 2 3 4 5 6))
+ (while (< i 3))
+ (find i (> i 12) :on-failure 27))
+ #+end_src
+
+ Like in Common Lisp's Iterate package, if =TEST= is a sharp-quoted symbol,
+ such as ~#'cl-evenp~, then the test expression is treated as applying that
+ function to the value of =EXPR=.
+ #+begin_src emacs-lisp
+ ;; => 2
+ (loopy (list i '(1 2 3 4 5 6))
+ ;; (find i (cl-evenp i))
+ (find i #'cl-evenp))
+ #+end_src
+
+ To be consistent with other commands, =ON-FAILURE= is evaluated at the
+ start of the loop, even though that is not necessarily where it is used.
+
+ #+BEGIN_SRC emacs-lisp
;; Value of `:on-failure' gotten at the start of the loop:
;; => 27
(loopy (with (on-fail 27))
@@ -5225,11 +5240,10 @@ makes use of more convenient Emacs Lisp libraries and
can be seen in the library
(cons 'progn (nreverse if-true-main-body))))
;; Return the new, full list of instructions.
- (cons `(loopy--main-body
- . (if ,condition
- ,if-true-main-body
- ,@(nreverse if-false-main-body)))
- (nreverse full-instructions)))))
+ `((loopy--main-body (if ,condition
+ ,if-true-main-body
+ ,@(nreverse if-false-main-body)))
+ ,@(nreverse full-instructions)))))
#+END_SRC
In general, the code of command parsers is not complicated. The hardest part
of
diff --git a/doc/loopy.texi b/doc/loopy.texi
index 825c41d7a99..406b9aeb86e 100644
--- a/doc/loopy.texi
+++ b/doc/loopy.texi
@@ -746,7 +746,7 @@ You should keep in mind that commands are evaluated in
order. This means that
attempting something like the below example might not do what you expect, as
@samp{i}
is assigned a value from the list after collecting @samp{i} into @samp{coll}.
-@float Listing,orga23c8aa
+@float Listing,orgb677e2e
@lisp
;; => (nil 1 2)
(loopy (collect coll i)
@@ -935,7 +935,7 @@ the flag @samp{dash} provided by the package
@samp{loopy-dash}.
Below are two examples of destructuring in @code{cl-loop} and @code{loopy}.
-@float Listing,orgea50e00
+@float Listing,org1e2c3e4
@lisp
;; => (1 2 3 4)
(cl-loop for (i . j) in '((1 . 2) (3 . 4))
@@ -950,7 +950,7 @@ Below are two examples of destructuring in @code{cl-loop}
and @code{loopy}.
@caption{Destructuring values in a list.}
@end float
-@float Listing,org5e2a634
+@float Listing,org3b108b1
@lisp
;; => (1 2 3 4)
(cl-loop for elem in '((1 . 2) (3 . 4))
@@ -3934,13 +3934,6 @@ never non-nil, then @samp{VAR} is set to the value of
@samp{ON-FAILURE}, if prov
This command also has the alias @samp{finding}.
-If the loop is left early and @samp{TEST} was never non-nil, this is the same
as a
-normal failure and @samp{VAR} will be set to the value of @samp{ON-FAILURE}, if
-provided.
-
-To be consistent with other commands, @samp{ON-FAILURE} is evaluated at the
-start of the loop, even though that is not necessarily where it is used.
-
@lisp
;; => (13 (1 2))
(loopy (list i '(1 2 3 4 5 6 7 8))
@@ -3956,15 +3949,37 @@ start of the loop, even though that is not necessarily
where it is used.
(loopy (list i '(1 2 3 4 5 6))
(find i (> i 12) :on-failure 27))
+;; => nil
+(loopy (list i '(1 2 3 4 5 6))
+ (find nil (> i 3) :on-failure 27))
+@end lisp
+
+If the loop is left early and @samp{TEST} was never non-nil, then this is the
same
+as a normal failure and @samp{VAR} will be set to the value of
@samp{ON-FAILURE}, if
+provided.
+
+@lisp
;; => 27
(loopy (list i '(1 2 3 4 5 6))
(while (< i 3))
(find i (> i 12) :on-failure 27))
+@end lisp
-;; => nil
+Like in Common Lisp's Iterate package, if @samp{TEST} is a sharp-quoted symbol,
+such as @code{#'cl-evenp}, then the test expression is treated as applying that
+function to the value of @samp{EXPR}.
+
+@lisp
+;; => 2
(loopy (list i '(1 2 3 4 5 6))
- (find nil (> i 3) :on-failure 27))
+ ;; (find i (cl-evenp i))
+ (find i #'cl-evenp))
+@end lisp
+
+To be consistent with other commands, @samp{ON-FAILURE} is evaluated at the
+start of the loop, even though that is not necessarily where it is used.
+@lisp
;; Value of `:on-failure' gotten at the start of the loop:
;; => 27
(loopy (with (on-fail 27))
@@ -4971,7 +4986,7 @@ using the @code{let*} special form.
This method recognizes all commands and their aliases in the user option
@code{loopy-parsers}.
-@float Listing,orge907358
+@float Listing,org50bbb64
@lisp
;; => ((-9 -8 -7 -6 -5 -4 -3 -2 -1)
;; (0)
@@ -5553,7 +5568,7 @@ between aliases and preferred names (which are the ones
commonly used and listed
first in this document). We continue to use the word ``alias'' for its common
definition rather than to suggest a difference in the code.
-@float Listing,org3b20adc
+@float Listing,org23481af
@lisp
;; => ("a" "b" "c" "d")
(loopy (array i "abcd")
@@ -5769,11 +5784,10 @@ ARG is of the form (if CONDITION IF-TRUE &rest
IF-FALSE)."
(cons 'progn (nreverse if-true-main-body))))
;; Return the new, full list of instructions.
- (cons `(loopy--main-body
- . (if ,condition
- ,if-true-main-body
- ,@@(nreverse if-false-main-body)))
- (nreverse full-instructions)))))
+ `((loopy--main-body (if ,condition
+ ,if-true-main-body
+ ,@@(nreverse if-false-main-body)))
+ ,@@(nreverse full-instructions)))))
@end lisp
In general, the code of command parsers is not complicated. The hardest part
of
