Stops: Better Guards in Emacs Lisp

Stops provides two small guard macros for Emacs Lisp:

• stops-if! signals an error when a condition is non-nil.
• stops-if-not! signals an error when a condition is nil.

Both macros return t when the guard passes. Both accept :error-type and :error-message keyword arguments. The error message may be a literal string or any Emacs Lisp expression that evaluates to a string.

Installation

Clone this repository or download stops.el and place it in your Emacs load-path. Then add the following line to your Emacs configuration:

(require 'stops)

Usage

Use stops-if! when a true condition should stop execution.

(defun divide (x y)
  (stops-if! (zerop y)
    :error-message (format "Cannot divide %S by zero" x))
  (/ x y))

Use stops-if-not! when a false condition should stop execution.

(defun first-item (xs)
  (stops-if-not! (consp xs)
    :error-message (format "Expected a non-empty list, got %S" xs))
  (car xs))

When no error message is provided, Stops creates a message from the guard condition.

(stops-if-not! (integerp x))

Signals an error with a message like:

stops-if-not!: condition was nil: (integerp x)

Formatted Messages

:error-message may be a literal string or any Emacs Lisp expression that evaluates to a string. Use format when the message should include runtime values.

(stops-if-not! (natnump x)
  :error-message (format "Expected a natural number, got %S" x))

The message expression is evaluated only when the guard fails.

API

stops-if!

(stops-if! CONDITION &key ERROR-TYPE ERROR-MESSAGE)

Signal an error if CONDITION is non-nil. Return t otherwise.

ERROR-TYPE defaults to error. ERROR-MESSAGE, when non-nil, is used as the error message. It may be a literal string or an expression that evaluates to a string.

(stops-if! (member user blocked-users)
  :error-type 'user-error
  :error-message (format "User %S is blocked" user))

stops-if-not!

(stops-if-not! CONDITION &key ERROR-TYPE ERROR-MESSAGE)

Signal an error if CONDITION is nil. Return t otherwise.

ERROR-TYPE defaults to error. ERROR-MESSAGE, when non-nil, is used as the error message. It may be a literal string or an expression that evaluates to a string.

(stops-if-not! (natnump x)
  :error-type 'wrong-type-argument
  :error-message (format "Expected a natural number, got %S" x))

Documentation Site

Build the static documentation site with:

make docs

The generated site is written to public/ and copied to docs/index.html for local review. The build-main GitHub Actions workflow builds this site and uploads it as a GitHub Pages artifact named github-pages. To publish it, configure GitHub Pages for this repository to use GitHub Actions as the publishing source.

Development

Run the test suite with:

make test

Run byte-compilation, tests, and package linting with:

make check

License

Stops is released under the MIT License. See LICENSE for details.

Version

This is the 1.0.1 release for Stops.