steve losh
 

Posted on July 9, 2018.

I haven’t been writing much lately because I’ve been in the process of switching my life over to Linux from OS X. I finally managed to get my blog infrastructure running again, so let’s take a look at some deceptively-tricky Common Lisp macros: when-let and if-let (and their let* counterparts).

Introduction

I first heard of the when-let and if-let macros when I learned Clojure a few years ago. They’re used like let to bind values to variables, but if a value is nil then when-let will return nil without running the body, and if-let will execute its alternative branch.

Let’s implement them in Common Lisp. Once we’re done writing them we’ll use them like this:

(when-let ((name 'steve))
  (format t "Hello, ~A" name))

; => Hello, STEVE

(when-let ((name nil))
  (format t "Hello, ~A" name))

; => Nothing printed, nil returned

(if-let ((name nil))
  (format t "Hello, ~A" name)
  (format t "Hello, unnamed person!"))

; => Hello, unnamed person!

A First Attempt

A simple first attempt at writing when-let might look something like this:

(defmacro when-let (binding &body body)
  "Bind `binding` and execute `body`, short-circuiting on `nil`.

  This macro combines `when` and `let`.  It takes a binding and binds
  it like `let` before executing `body`, but if the binding's value
  evaluates to `nil`, then `nil` is returned.

  Examples:

    (when-let ((a 1))
      (list a))
    ; =>
    (1)

    (when-let ((a nil))
      (list a))
    ; =>
    NIL

  "
  (destructuring-bind ((symbol value)) binding
    `(let ((,symbol ,value))
       (when ,symbol
         ,@body))))

A first attempt at if-let looks similar:

(defmacro if-let (binding then else)
  "Bind `binding` and execute `then` if true, or `else` otherwise.

  This macro combines `if` and `let`.  It takes a binding and binds
  it like `let` before executing `then`, but if the binding's value
  evaluates to `nil` the `else` branch is executed (with no binding
  in effect).

  Examples:

    (if-let ((a 1))
      (list a)
      'nope)
    ; =>
    (1)

    (if-let ((a nil))
      (list a)
      'nope)
    ; =>
    NOPE

  "
  (destructuring-bind ((symbol value)) binding
    `(let ((,symbol ,value))
       (if ,symbol
         ,then
         ,else))))

This is a decent attempt at a first pass, but already there are a couple of things to note.

First: we have documentation, with examples! The docstrings are longer than the macros themselves, and this is fine! I always prefer to err on the side of being more clear than saving space. If you’re a little more verbose than necessary some experts might have to flick their scroll wheels, but if you’re too terse you can leave someone wallowing in confusion. Experts should know how to skim documentation quickly if they’re really experts, so help out the newer people and be clear!

I didn’t make the else branch optional like it is in Common Lisp’s if because one-armed ifs are a stylistic abomination.

We could have added some check-type statements to make sure the symbol is actually a symbol, but since it’s getting compiled to a let the error will be caught there immediately anyway.

Multiple Bindings

Our first attempt works, but only supports a single binding. Clojure’s versions of these macros quit here, but we can do better. Let’s make our macros support multiple bindings. First we’ll upgrade when-let:

(defmacro when-let (bindings &body body)
  "Bind `bindings` and execute `body`, short-circuiting on `nil`.

  This macro combines `when` and `let`.  It takes a list of bindings
  and binds them like `let` before executing `body`, but if any
  binding's value evaluates to `nil`, then `nil` is returned.

  Examples:

    (when-let ((a 1)
               (b 2))
      (list a b))
    ; =>
    (1 2)

    (when-let ((a nil)
               (b 2))
      (list a b))
    ; =>
    NIL

  "
  (let ((symbols (mapcar #'first bindings)))
    `(let ,bindings
       (when (and ,@symbols)
         ,@body))))

And now if-let:

(defmacro if-let (bindings then else)
  "Bind `bindings` and execute `then` if all are true, or `else` otherwise.

  This macro combines `if` and `let`.  It takes a list of bindings and
  binds them like `let` before executing `then`, but if any binding's
  value evaluates to `nil` the `else` branch is executed (with no
  bindings in effect).

  Examples:

    (if-let ((a 1)
             (b 2))
      (list a b)
      'nope)
    ; =>
    (1 2)

    (if-let ((a nil)
             (b 2))
      (list a b)
      'nope)
    ; =>
    NOPE

  "
  (let ((symbols (mapcar #'first bindings)))
    `(let ,bindings
       (if (and ,@symbols)
         ,then
         ,else))))

Note how we’ve updated the docstrings to be clear about the new behavior: if any binding is nil, the alternate case takes over.

We’ve also updated the parameter names to be bindings (plural). One thing I love about Common Lisp is that it’s a Lisp 2, so you can almost always use nice names for function parameters instead of mangling them to avoid shadowing functions (e.g. (defun filter (function list) ...) instead of (defun filter (fn lst) ...)). Take advantage of this and give your parameters descriptive, pronounceable names. You’ll thank yourself every time your editor shows you the arglist.

If you’ve read other blog posts about implementing these macros, this is where they probably stopped. But let’s keep going, there’s still much more to dig into!

Adding Some Stars

Now that we’ve got if-let and when-let, the obvious next step is to add if-let* and when-let*. We could do this by changing the let each macro emits to a let*, but before we rush ahead let’s think about how people will use these macros to see if that change would make sense.

The point of using a let* instead of a let is so that later variables can refer back to earlier ones:

(let* ((name (read-string))
       (length (length name)))
  ; ...
  )

The point of using our when- and if- variants is to short-circuit and escape on nil. With the way our macros are currently written, all the variables get bound before they all get checked for nil in the and. This works for the -let variants but isn’t ideal for the new -let* variants. If we’re using when-let* it would be nice if the later variables could assume the earlier ones are non-nil.

This means we’ll want to bail out immediately after the first nil value is detected. This is a little bit trickier than what we’ve currently got. There are a number of ways we could do it, but I’ll save us from hitting a dead-end rabbit hole later and implement when-let* like this:

(defmacro when-let* (bindings &body body)
  "Bind `bindings` serially and execute `body`, short-circuiting on `nil`.

  This macro combines `when` and `let*`.  It takes a list of bindings
  and binds them like `let*` before executing `body`, but if any
  binding's value evaluates to `nil` the process stops and `nil` is
  immediately returned.

  Examples:

    (when-let* ((a (progn (print :a) 1))
                (b (progn (print :b) (1+ a)))
      (list a b))
    ; =>
    :A
    :B
    (1 2)

    (when-let* ((a (progn (print :a) nil))
                (b (progn (print :b) (1+ a))))
      (list a b))
    ; =>
    :A
    NIL

  "
  (alexandria:with-gensyms (block)
    `(block ,block
       (let* ,(loop :for (symbol value) :in bindings
                    :collect `(,symbol (or ,value
                                           (return-from ,block nil))))
         ,@body))))

There are a few things we can talk about here before we move on to if-let*.

First: we’ve documented the macro. The examples are a little more verbose than the previous ones, but the added side effects explicitly show the short-circuiting evaluation.

This implementation is much less trivial than the ones we’ve got so far, so let’s look at a macroexpansion to see what’s happening:

(macroexpand-1
  '(when-let* ((a nil)
               (b (1+ a)))
    (list a b)))
; =>
(BLOCK #:BLOCK563
  (LET* ((A (OR NIL    (RETURN-FROM #:BLOCK563 NIL)))
         (B (OR (1+ A) (RETURN-FROM #:BLOCK563 NIL))))
    (LIST A B)))

The when-let* expands into a block wrapped around a let*. As we’re binding each variable it’s checking for nil with or. If it ever sees nil it will return from the block immediately to escape. If it never sees nil it will eventually reach the body and return normally.

We could have used a series of nested lets and ifs here, and it would have been easier to read. But the fact that all the variables are bound in a single let* will be important later, so you’re just going to have to trust me for now.

We’ve named the block with a gensym to avoid clobbering any nil block the user might already have set up. I explicitly specified the nil return value in the return-from, but this isn’t required because it’s optional.

if-let* is a more difficult, because we need to make sure the appropriate branch gets evaluated:

(defmacro if-let* (bindings then else)
  "Bind `bindings` serially and execute `then` if all are true, or `else` otherwise.

  This macro combines `if` and `let*`.  It takes a list of bindings and
  binds them like `let*` before executing `then`, but if any binding's
  value evaluates to `nil` the process stops and the `else` branch is
  immediately executed (with no bindings in effect).

  Examples:

    (if-let* ((a (progn (print :a) 1))
              (b (progn (print :b) (1+ a)))
      (list a b)
      'nope)
    ; =>
    :A
    :B
    (1 2)

    (if-let* ((a (progn (print :a) nil))
              (b (progn (print :b) (1+ a))))
      (list a b)
      'nope)
    ; =>
    :A
    NOPE

  "
  (alexandria:with-gensyms (outer inner)
    `(block ,outer
       (block ,inner
         (let* ,(loop :for (symbol value) :in bindings
                      :collect `(,symbol (or ,value
                                             (return-from ,inner nil))))
           (return-from ,outer ,then)))
       ,else)))

This is a little hairy, so let’s break down what’s happening. An if-let* will macroexpand into something like:

(block outer
  (block inner
    (let* (...bindings...)
      (return-from outer then)))
  else)

We set up a pair of blocks and begin binding the variables. If all the bindings succeed we return the then branch from the outermost block (and yes, before you go check: return-from works fine with multiple values).

If any of the bindings fail we return from the inner block immediately. This skips all the remaining bindings plus the then and continues along to the else, which executes and returns normally.

A full macroexpansion ends up looking like this:

(macroexpand-1
  '(if-let* ((a nil)
             (b (1+ a)))
     (list a b)
     'nope))
; =>
(BLOCK #:OUTER568
  (BLOCK #:INNER569
    (LET* ((A (OR NIL    (RETURN-FROM #:INNER569)))
           (B (OR (1+ A) (RETURN-FROM #:INNER569))))
      (RETURN-FROM #:OUTER568 (LIST A B))))
  'NOPE)

It wouldn’t be ideal to implement if-let* as a nested series of lets and ifs, because you’d need to duplicate the else code at each level. The nested pair of blocks might be a little harder to understand at first, but they only include the else in a single place (and will be important for another reason soon).

Consistency

Now that we’ve got when-let* and if-let* short-circuiting on each binding, it probably makes sense to change when-let and if-let to behave the same way, instead of checking after all the variables are bound. Although the later variables don’t rely on the earlier ones for these variants, it would be good if the behavior were consistent.

To do this we can take our -let* versions and change the let* inside to a let, update the documentation, and that’s it:

(defmacro when-let (bindings &body body)
  "Bind `bindings` in parallel and execute `body`, short-circuiting on `nil`.

  This macro combines `when` and `let`.  It takes a list of bindings and
  binds them like `let` before executing `body`, but if any binding's value
  evaluates to `nil` the process stops and `nil` is immediately returned.

  Examples:

    (when-let ((a (progn (print :a) 1))
               (b (progn (print :b) 2))
      (list a b))
    ; =>
    :A
    :B
    (1 2)

    (when-let ((a (progn (print :a) nil))
               (b (progn (print :b) 2)))
      (list a b))
    ; =>
    :A
    NIL

  "
  (alexandria:with-gensyms (block)
    `(block ,block
       (let ,(loop :for (symbol value) :in bindings
                   :collect `(,symbol (or ,value
                                          (return-from ,block nil))))
         ,@body))))

(defmacro if-let (bindings then else)
  "Bind `bindings` in parallel and execute `then` if all are true, or `else` otherwise.

  This macro combines `if` and `let`.  It takes a list of bindings and
  binds them like `let` before executing `then`, but if any binding's value
  evaluates to `nil` the process stops and the `else` branch is immediately
  executed (with no bindings in effect).

  Examples:

    (if-let ((a (progn (print :a) 1))
             (b (progn (print :b) 2))
      (list a b)
      'nope)
    ; =>
    :A
    :B
    (1 2)

    (if-let ((a (progn (print :a) nil))
             (b (progn (print :b) 2)))
      (list a b)
      'nope)
    ; =>
    :A
    NOPE

  "
  (alexandria:with-gensyms (outer inner)
    `(block ,outer
       (block ,inner
         (let ,(loop :for (symbol value) :in bindings
                     :collect `(,symbol (or ,value
                                            (return-from ,inner nil))))
           (return-from ,outer ,then)))
       ,else)))

Declarations

Before we finish, we should make sure we’ve done things right. Something that’s often forgotten when making new control structures with macros is handling declarations properly. When writing a normal let, you can put declarations immediately inside the body, like this:

(let ((foo (some-function))
      (bar (some-other-function)))
  (declare (optimize safety)
           (type integer foo)
           (type string bar))
  (do-something foo bar))

If we think about how our when-let (and the -let* version) macroexpands we’ll see that we don’t need to do anything — it will work fine the way we’ve written it:

(macroexpand-1
  '(when-let ((foo (some-function))
              (bar (some-other-function)))
     (declare (optimize safety)
              (type integer foo)
              (type string bar))
     (do-something foo bar)))
; =>
(BLOCK #:BLOCK586
  (LET ((FOO (OR (SOME-FUNCTION) (RETURN-FROM #:BLOCK586 NIL)))
        (BAR (OR (SOME-OTHER-FUNCTION) (RETURN-FROM #:BLOCK586 NIL))))
    (DECLARE (OPTIMIZE SAFETY)
             (TYPE INTEGER FOO)
             (TYPE STRING BAR))
    (DO-SOMETHING FOO BAR)))

This is why I insisted on implementing the macros with a single let binding all the variables. If we tried to do this with a series of nested lets and ifs we’d have to try to parse the declarations and put the appropriate ones for each variable under the corresponding let, and this would be an absolute nightmare (plus you wouldn’t even be able to exclude nil from the type, because the if wouldn’t happen until after the declaration!).

Unfortunately if-let is going to be some more work. Let’s think about an example:

(if-let ((foo (some-function))
         (bar (some-other-function)))
  (declare (optimize safety)
           (type integer foo)
           (type string bar))
  (do-something foo bar)
  (do-something-else))

We’re going to want the declarations to only apply to the then branch, because that’s the branch that has the variables whose types we might want to declare. If the user wants some declarations in the else branch they can wrap that branch in a locally and add them there.

We’re going to need a way to grab any declarations the user has given out of the body of the if-let. Luckily Alexandria has a function called parse-body that will do this for us.

(defmacro if-let (bindings &body body)
  "Bind `bindings` in parallel and execute `then` if all are true, or `else` otherwise.

  `body` must be of the form `(...optional-declarations... then else)`.

  This macro combines `if` and `let`.  It takes a list of bindings and
  binds them like `let` before executing the `then` branch of `body`, but
  if any binding's value evaluates to `nil` the process stops there and the
  `else` branch is immediately executed (with no bindings in effect).

  If any `optional-declarations` are included they will only be in effect
  for the `then` branch.

  Examples:

    (if-let ((a (progn (print :a) 1))
             (b (progn (print :b) 2)))
      (list a b)
      'nope)
    ; =>
    :A
    :B
    (1 2)

    (if-let ((a (progn (print :a) nil))
             (b (progn (print :b) 2)))
      (list a b)
      'nope)
    ; =>
    :A
    NOPE

  "
  (alexandria:with-gensyms (outer inner)
    (multiple-value-bind (body declarations) (alexandria:parse-body body)
      (destructuring-bind (then else) body
        `(block ,outer
           (block ,inner
             (let ,(loop :for (symbol value) :in bindings
                         :collect `(,symbol (or ,value
                                                (return-from ,inner nil))))
               ,@declarations
               (return-from ,outer ,then)))
           ,else)))))

Whew! We parse the body with parse-body, destructure what’s left of it (to make sure we have our two branches), and shove the declarations where they belong.

if-let* is exactly the same, but with a let* in the macro. I’ll let you write that one yourself.

Result

We’ve now got when-let, when-let*, if-let, and if-let* working properly. They all support multiple bindings, short-circuit appropriately, handle declarations correctly, and are documented clearly.