wilfred / loop.el

friendly imperative loop structures for Emacs lisp

loop.el --- friendly imperative loop structures for Emacs lisp

Emacs lisp is missing loop structures familiar to users of newer languages. This library adds a selection of popular loop structures as well as break and continue.

loop.el also has full unit tests.

Table of Contents

• loop.el --- friendly imperative loop structures for Emacs lisp
  • Contents
    • loop-while
    • loop-do-while
    • loop-until
    • loop-for-each
    • loop-for-each-line
    • loop-break
    • loop-continue
  • Alternatives
  • Changelog
  • Running the tests

Contents

loop-while

Repeatedly evaluate BODY while CONDITION is non-nil.

loop-while (condition body...)

Example:

(let ((x 0)
      (sum 0))
  ;; sum the numbers 0 to 9
  (loop-while (< x 10)
    (setq sum (+ sum x))
    (setq x (1+ x))))

loop-do-while

Evaluate BODY, then repeatedly BODY while CONDITION is non-nil.

loop-do-while (condition body...)

Example:

(let ((x 0)
      (sum 0))
  ;; our condition is false on the first iteration
  (loop-do-while (and (> x 0) (< x 10))
    (setq sum (+ sum x))
    (setq x (1+ x))))

loop-until

Repeatedly evaluate BODY until CONDITION is non-nil.

loop-until (condition body...)

Example:

(let ((x 0)
      (sum 0))
  ;; sum the numbers 0 to 9
  (loop-until (= x 10)
    (setq sum (+ sum x))
    (setq x (1+ x))))

loop-for-each

For every item in LIST, evaluate BODY with VAR bound to that item.

• loop-for-each (var list body...)

Example:

(let ((sum 0))
  (loop-for-each x (list 1 2 3 4 5 6 7 8 9)
    (setq sum (+ sum x))))

loop-for-each-line

For every line in the buffer, put point at the start of the line and execute BODY.

• loop-for-each-loop (body...)

Example:

;; Count headings in a markdown buffer.
(let ((heading-count 0))
  (loop-for-each-line
    (when (looking-at "#")
      (setq heading-count (+ heading 1))))

loop-break

Terminate evaluation of a loop-while, loop-do-while, loop-for-each, or loop-for-each-line block. If there are nested loops, breaks out of the innermost loop.

loop-break ()

Example:

(let ((sum 0))
  ;; sum the numbers 1 to 5
  (loop-for-each x (list 1 2 3 4 5 6 7 8 9)
    (setq sum (+ sum x))
    (when (= x 5)
      (loop-break)))
  sum)

loop-continue

Skip the rest of the current loop-while, loop-do-while, or loop-for-each block and continue to the next iteration. If there are nested loops, applies to the innermost loop.

loop-continue ()

Example:

(let ((sum 0))
  ;; sum the numbers 1, 3, 4, 5
  (loop-for-each x (list 1 2 3 4 5)
    (when (= x 2)
      (loop-continue))
    (setq sum (+ sum x))))

Alternatives

• while and dolist are built-in loop structures
• The cl-loop macro in cl-lib
• -each in dash.el

Changelog

• v1.3 loop-for-each-line now works even if point moves around. Inside loop-for-each-line, it is now set to the current line. Added loop-return.
• v1.2 Added loop-for-each-line. Also added edebug support, so you can step through loops in loop.el.
• v1.1 Added loop-continue
• v1.0 loop-for-each now takes three arguments: (VAR LIST BODY...)
• v0.3 Added loop-until
• v0.2 Basic working implementation

Running the tests

M-x loop-run-tests

loop.el's Issues

Please add a prefix to test-helper.el to avoid conflicts with 68 other packages

There exist at least 69 packages that contain a file named test-helper.el that also provides the feature test-helper.

This leads to issues for users who have at least two of these packages installed. It is unlikely that such a user would be able to run the tests of all of those packages. If the primary test file of one of those packages does (require 'test-helper), then it is undefined which of the various test-helper.el files gets loaded. Which it is, depends on the order of the load-path.

To avoid this conflicts, you should rename your test-helper.el to <your-package>-test-helper.el and adjust the feature accordingly.

Also don't forget to update the require form in your primary test file and/or update references to the library/feature elsewhere. Also, if your primary test file is named something like test.el, then please consider renaming that too (same for any other utility elisp files your repositoroy may contain).

Thanks!

PS: This issue is a bit generic because I had to open 69 issues.

dolist and dotimes are not part of cl-lib

See subr.el. These can be used just fine in existing code, cl-dolist and cl-dotimes merely provide you the ability of breaking out early.

In the example of loop-break, the form is not returning sum. It will be more clear and consistent this way.

(let ((sum 0))
  ;; sum the numbers 1 to 5
  (loop-for-each x (list 1 2 3 4 5 6 7 8 9)
    (setq sum (+ sum x))
    (when (= x 5)
      (loop-break)))
  sum)

Emacs Lisp Coding Conventions

Please, take a look at Emacs Lisp Coding Conventions. The relevant extract:

• If you need Common Lisp extensions, use the cl-lib library rather than the old cl library. The latter does not use a clean namespace (i.e., its definitions do not start with a ‘cl-’ prefix). If your package loads cl at run time, that could cause name clashes for users who don't use that package.
  • There is no problem with using the cl package at compile time, with (eval-when-compile (require 'cl)). That's sufficient for using the macros in the cl package, because the compiler expands them before generating the byte-code. It is still better to use the more modern cl-lib in this case, though.