metabang-bind user guide

Introduction

Some examples

Bind as a replacement for let

Bind with multiple-values and destructuring

Bind with property lists

Bind with structures

Bind with classes

Bind with arrays

Bind with regular expressions

Bind with flet and labels

More bindings

lambda-bind

Extending bind yourself

Introduction

Bind combines let, destructuring-bind and multiple-value-bind and a whole lot more into a single form. It has two goals:

  1. reduce the number of nesting levels

  2. make it easier to understand all of the different forms of destructuring and variable binding by unifying the multiple forms of syntax and reducing special cases.

Bind is extensible. It handles the traditional multiple-values, destructuring, and let-forms as well as property-lists, classes, and structures. Even better, you can create your own binding forms to make your code cleaner and easier to follow (for others and yourself!).

Simple bindings are as in let*. Destructuring is done if the first item in a binding is a list. Multiple value binding is done if the first item in a binding is a list and the first item in the list is the keyword ':values'.

Some examples

Bind mimics let in its general syntax:

(bind (&rest bindings) <body>) 

where each binding can either be an symbol or a list. If the binding is an atom, then this atom will be bound to nil within the body (just as in let). If it is a list, then it will be interpreted depending on its first form.

(bind (a  
       (...))  
  ...)  

Bind as a replacement for let

You can use bind as a direct replacement for let*:

(bind ((a 2) b)  
  (list a b))  
=> (2 nil) 

As in let*, atoms are initially bound to nil.

Bind with multiple-values and destructuring

Suppose we define two silly functions:

(defun return-values (x y)  
  (values  x y))  
 
(defun return-list (x y)  
  (list x y)) 

How could we use bind for these:

(bind (((:values a b) (return-values 1 2))  
       ((c d) (return-list 3 4)))  
  (list a b c d))  
=> (1 2 3 4) 

Note that bind makes it a little easier to ignore variables you don't care about. Suppose I've got a function ijara that returns 3 values and I happen to need only the second two. Using destructuring-bind, I'd write:

(destructuring-bind (foo value-1 value-2)  
    (ijira)  
  (declare (ignore foo))  
  ...) 

With bind, you use nil or _ in place of a variable name and it will make up temporary variables names and add the necessary declarations for you.

(bind (((_ value-1 value-2) (ijira)))  
  ...)  

Bind with property lists

A property-list or plist is a list of alternating keywords and values. Each keyword specifies a property name; each value specifies the value of that name.

(setf plist  
  '(:start 368421722 :end 368494926 :flavor :lemon  
    :content :ragged) 

You can use getf to find the current value of a property in a list (and setf to change them). The optional third argument to getf is used to specify a default value in case the list doesn't have a binding for the requested property already.

(let ((start (getf plist :start 0))  
      (end (getf plist :end))  
      (fuzz (getf plist :fuzziness 'no)))  
  (list start end fuzz))  
=> (368421722 368494926 no) 

The binding form for property-lists is as follows:

(:plist property-spec*) 

where each property-spec is an atom or a list of up to three elements:

Putting this altogether we can code the above let statement as:

(bind (((:plist (start _ 0) end (fuzz fuzziness 'no))  
  plist))  
=> (list start end fuzz)) 

(which takes some getting used to but has the advantage of brevity).

Bind with structures

Structure fields are accessed using a concatenation of the structure's conc-name and the name of the field. Bind therefore needs to know two things: the conc-name and the field-names. The binding-form looks like

(:structure <conc-name> structure-spec*) 

where each structure-spec is an atom or list with two elements:

So if we have a structure like:

(defstruct minimal-trout  
  a b c)  
 
(setf trout (make-minimal-trout :a 2 :b 3 :c 'yes)) 

We can bind these fields using:

(bind (((:structure minimal-trout- (my-name a) b c)  
        trout))  
  (list my-name b c))  
=> (2 3 yes) 

Bind with classes

You can read the slot of an instance with an accessor (if one exists) or by using slot-value 1 . Bind also provides two slot-binding mechanisms: :slots and :accessors. Both look the same:

(:slots slot-spec*)  
(:accessors accessor-spec*) 

Where both slot-spec and accessor-spec can be atoms or lists with two elements.

Support we had a class like:

(defclass wicked-cool-class ()  
  ((a :initarg :a :accessor its-a)  
   (b :initarg :b :accessor b)  
   (c :initarg :c :accessor just-c))) 

If we don't mind using the slot-names as variable names, then we can use the simplest form of :slots:

(bind (((:slots a b c)  
	(make-instance 'wicked-cool-class  
		       :a 1 :b 2 :c 3)))  
  (list a b c))  
==> (1 2 3) 

We can also change the names within the context of our bind form:

(bind (((:slots a b (dance-count c))  
	(make-instance 'wicked-cool-class  
		       :a 1 :b 2 :c 3)))  
  (list a b dance-count))  
==> (1 2 3) 

Similarly, we can use :accessors with variable names that are the same as the accessor names...

(bind (((:accessors its-a b just-c)  
	(make-instance 'wicked-cool-class  
		       :a 1 :b 2 :c 3)))  
  (list its-a b just-c))  
==> (1 2 3) 

or that are different:

(bind (((:accessors (a its-a) b (c just-c))  
	(make-instance 'wicked-cool-class  
		       :a 1 :b 2 :c 3)))  
  (list a b c))  
==> (1 2 3) 

Bind with arrays

Tamas Papp had the idea of letting bind handle arrays too. For example,

(bind ((#(a b c) #(1 2 3)))  
  (list a b c))  
==> (1 2 3) 

One quick method definition and a few unit-tests later and bind does!

Bind with regular expressions

If you have CL-PPCRE or run with Allegro Common Lisp, you can use bind with regular expressions too. The syntax is

(:re expression &rest vars) string) 

and will bind each grouped item in the expression to the corresponding var. For example:

(bind (((:re "(\\w+)\\s+(\\w+)\\s+(\\d{1,2})\\.(\\d{1,2})\\.(\\d{4})"  
	     fname lname nil month year) "Frank Zappa 21.12.1940"))  
  (list fname lname month year)) 

The body of bind form will be evaluated even if the expression does not match.

Bind with flet and labels

Bind can even be used as a replacement for flet and labels. The syntax is

(:flet function-name (arguments*)) definition)  
 
(:labels function-name (arguments*)) definition) 

for example:

(bind (((:flet square (x)) (* x x)))  
  (square 4))  
==> 16  
 
(bind (((:labels my-oddp (x))  
   (cond ((<= x 0) nil)  
 	 ((= x 1) t)  
	 (t (my-oddp (- x 2))))))  
    (my-oddp 7))  
==> t 

Note that bind currently expands each binding-form into a new context. In particular, this means that

(bind (((:flet x (a)) (* a 2))  
       ((:flet y (b)) (+ b 2)))  
  ...) 

expands as

(flet ((x (a) (progn (* a 2))))  
  (flet ((y (b) (progn (+ b 2))))  
    ...)) 

rather than

(flet ((x (a) (progn (* a 2)))  
       (y (b) (progn (+ b 2))))  
    ...) 

Generally speaking, this shouldn't make much of a difference.

More bindings

Since bind is extensible and I'm fallible, there are probably things bind can do that haven't made it into this guide. Use the following commands to see what bind can do:

binding-forms
function
Return a list of all binding-forms that bind supports in alphabetical order.
binding-form-docstring name
function
Returns the docstring for a binding form named name.
binding-form-groups
function
Return a list of the available binding-forms grouped into their synonyms.
binding-form-synonyms name
function

Return a list of synonyms for the binding-form name.

For example

> (binding-form-synonyms :accessors)  
(:accessors :writable-accessors) 

lambda-bind

Eric Schulte contributed lambda-bind (note, he called it lambdab but I dislike abbreviations so...):

lambda-bind (&rest instrs) &rest body
macro

Use `bind' to allow restructuring of argument to lambda expressions.

This lets you funcall and destructure simultaneously. For example

(let ((fn (lambda-bind ((a b) c) (cons a c))))  
  (funcall fn '(1 2) 3))  
;; => (1 . 3) 

Via eschulte (see git://gist.github.com/902174.git).

Extending bind yourself

Bind's syntax is extensible: the work for each binding-specification is handled by a generic function. This means that you can evolve bind to fit your program for whatever sort of data-structure makes sense for you. To make a binding form, you can either define a method for bind-generate-bindings or you can use the defbinding-form macro.

bind-generate-bindings kind variable-form value-form body declarations remaining-bindings
function

Handle the expansion for a particular binding-form.

kind specifies the binding form. It can be a type (e.g., symbol or array) or a keyword (e.g., :flet or :plist). variable-form and value-form are taken from the binding-form given to bind. E.g., if you have a bind like

(bind (((:values a b c) (foo))  
       (x 2))  
   (declare (optimize (speed 3)) (type simple-array a))  
   ...) 

then kind will be :values, variable-form will be the list (a b c) and value-form will be the expression (foo). bind-generate-bindings uses these variables as data to construct the generated code. body contains the rest of the code passed to bind (the ...) above in this case) and can usually be ignored. declarations contains all of the declarations from the bind form (e.g. the optimize (speed 3) and so on) and should be used to insert whatever declarations match at this particular point in the expansion. Use bind-filter-declarations to do this easily). Finally, remaining-bindings contains the rest of the binding-forms. It can also be safely ignored.

defbinding-form (name/s &key docstring remove-nils-p description use-values-p accept-multiple-forms-p) &body body
macro

Describe how bind should expand particular binding-forms.

defbinding-form links a name or type with an expansion. These definitions are used by bind at macro-expansion time to generate the code that actually does the bindings for you. For example:

(defbinding-form (symbol :use-values-p nil)  
  (if (keywordp kind)  
      (error "Don't have a binding form for ~s" kind)  
      `(let (,@(if values  
                 `((,variables ,values))  
                 `(,variables)))))) 

This binding form tells to expand clauses whose first element is a symbol using let. (It also gets bind to signal an error if the first element is a keyword that doesn't have a defined binding form.)

There are many more examples included in the source code.