Clojure: &env and &form

Inside the body of defmacro you can call &env and &form to get a bit of interesting information that may or may not be helpful.

Here's a few examples that demonstrate how &env and &form can be used.
(note: I'm using Clojure 1.2)

&env
By default &env is nil.

user=> (defmacro show-env [] (println &env))
#'user/show-env
user=> (show-env)
nil

However, if any bindings exist, &env gives you the names of the bindings as the keys of a map.

user=> (let [band "zeppelin" city "london"] (show-env))
{city #<LocalBinding clojure.lang.Compiler$LocalBinding@78ff9053>, band #<LocalBinding clojure.lang.Compiler$LocalBinding@525c7734>}

Okay, now we're getting somewhere. What's a Compiler$LocalBinding? I'm not exactly sure, and I've never bothered to look into it. I've been told that the 'values' from &env may change in the future, so I wouldn't rely on them anyway. Since I can't rely on them, I haven't found the need to look into what they are.

Back to the keys. They sure look like symbols.

user=> (defmacro show-env [] (println (keys &env)) (println (map class (keys &env))))
#'user/show-env
user=> (let [band "zeppelin" city "london"] (show-env))                              
(city band)
(clojure.lang.Symbol clojure.lang.Symbol)

As the example shows, they are definitely symbols. However, these symbols don't have a namespace.

user=> (defmacro show-env [] (println (keys &env)) (println (map namespace (keys &env))))
#'user/show-env
user=> (let [band "zeppelin" city "london"] (show-env))                                  
(city band)
(nil nil)

Since the symbols don't have a namespace there didn't seem to be much fun I could do with them; however, you can use the symbols in your macro to print the values, as the following example shows.

user=> (defmacro show-env [] (println (keys &env)) `(println ~@(keys &env)))                      
#'user/show-env
user=> (let [band "zeppelin" city "london"] (show-env))                     
(city band)
london zeppelin

Printing the values of bindings can be a helpful trick while you are debugging.
&form
&form can be used to get the original macro invocation.

user=> (defmacro show-form [] (println &form))                               
#'user/show-form
user=> (show-form)
(show-form)

Okay, not very interesting so far. It gets a bit more interesting when your macro takes a few arguments.

user=> (defmacro show-form [a b] (println &form))       
#'user/show-form
user=> (show-form 50 100)                        
(show-form 50 100)
user=> (show-form a 100) 
(show-form a 100)

So, you can get the arguments. Notice you can grab both 50 and 100.

user=> (defmacro show-form [a b] (println (next &form)))
#'user/show-form
user=> (show-form 50 100)                               
(50 100)
user=> (defmacro show-form [a b] (println (map class (next &form))))
#'user/show-form
user=> (show-form 50 100)                                           
(java.lang.Integer java.lang.Integer)

Interesting. So I have a few integers I can work with, if I wish. What about 'show-form'?

user=> (defmacro show-form [a b] (println (map class &form)))       
#'user/show-form
user=> (show-form 50 100)                                    
(clojure.lang.Symbol java.lang.Integer java.lang.Integer)

'show-form' is a symbol, as expected. Which brings us back to a previous example, shown again below.

user=> (defmacro show-form [a b] (println (map class &form)))
#'user/show-form
user=> (show-form a 100)                                     
(clojure.lang.Symbol clojure.lang.Symbol java.lang.Integer)

Okay, 'a' is also a symbol, unsurprising, but perhaps it's interesting since 'a' doesn't exist anywhere except in our invocation. You can probably do some interesting things here, like allow people to specify enum values and append the enum yourself.

user=> (ns user (:import [java.util.concurrent TimeUnit]))                                                     
java.util.concurrent.TimeUnit
user=> (defmacro time-units [& l] (->> (next &form) (map (partial str "TimeUnit/")) (map symbol) (cons 'list)))
#'user/time-units
user=> (time-units SECONDS MILLISECONDS)                                                                       
(#< SECONDS> #< MILLISECONDS>)

Would you want to use &form instead of just using the arguments (stored in l)? Probably not. This isn't an exercise in what you should do, but it does demonstrate what you could do.

So &form must be returning a list, right?

user=> (defmacro show-form [a b] (println (map class &form)) (println (class &form))) 
#'user/show-form
user=> (show-form 50 100)                                                            
(clojure.lang.Symbol java.lang.Integer java.lang.Integer)
clojure.lang.PersistentList

A list. Correct.

And, I'm in a macro, so I can do anything I want with this list. Maybe I just want to print the arguments. Easy enough.

user=> (defmacro show-form [a b] `(println ~@(next &form)))
#'user/show-form
user=> (show-form 50 100)                                  
50 100

Of course, there are a million things I could do. You get the idea.

One other interesting thing to note is that &form has metadata.

user=> (show-form 50 100)                                 
{:line 132}

Perhaps you don't care about line numbers, but they definitely can come in handy when you are writing a testing framework.

I use &form in expectations and I believe LazyTest uses &env. I guess you never know what you're going to need...

Clojure: Converting a Custom Collection to a Sequence

I've been doing a bit of clojure lately and I've often found myself looking to convert a custom collection to a sequence. Unfortunately, several custom collections from libraries that we use don't implement Iterable; therefore, I can't simply use the seq function to create a seq.

In Java it's common to simply use a for loop and a get method to iterate through custom collections that don't implement Iterable.

for (int i=0; i<fooCollection.size(); i++) {
  Foo foo = fooCollection.get(i);
}

There are patterns for doing something similar in Clojure; however, I much prefer to work with Sequences and functions that operate on Sequences. Shane Harvie and I added the following snippet to our code to quickly convert a custom collection to a seq.

(defmacro obj->seq [obj count-method]
  `(loop [result# []
          i# 0]
    (if (< i# (. ~obj ~count-method))
      (recur (conj result# (.get ~obj i#)) (inc i#))
      result#)))

Our first version only worked with a custom collection that had a .size() method; however, the second collection we ran into used a .length() method, so we created the above macro that allows you to specify the (size|length|count|whatever) method.

The obj->seq function can be used similar to the following example.

(let [positions (obj->seq position-collection size)]
  ; do stuff with positions
  )

I'm fairly new to Clojure, so please feel free to provide recommendations and feedback.

Macros Facilitate Expressive Code

Someone once asked me if I thought Clojure was more expressive than even Ruby. I didn't have enough information to form an opinion then, and I still don't now. However, I recently noticed something that led me to believe the answer could actually be yes.

I was looking through the code of clojure.test on Friday and I noticed something interesting. In clojure.test, the form(s) passed to the "is" macro are wrapped by a try/catch. It caught my eye because I often want to do the same thing in other languages, and usually I have to settle for much less elegant solutions.

Here's a bit of example code to help create some context

(deftest a-test
  (is (= 1 (some-function-that-throws-an-exception)))
  (println "this code still executes"))

For this example to work you'll have to ignore the fact that you probably don't want this behavior. In practice I prefer my tests to abort on the first failing assertion; however, in this blog entry I'm focusing on what's happening, not what I theoretically prefer.

In the example I call a function the same way I would anywhere else, and the framework has full control over what happens if my function throws an exception. This is accomplished when the "is" macro takes the forms and manipulates them into something similar to the original code, but with additional capabilities.

This particular example struck me as one where macros allow you to write only what you want, and the macro adds the additional behavior that you desire. However, the key is, you don't have to do anything special to get this additional behavior.

Consider trying to do the same thing in Ruby. In Test::Unit you would need an assert method that took a block.

def safe_assert_equal
  result = yield
  assert_equal result.first, result.last
rescue Exception=>e
  puts e
end

class Testable < Test::Unit::TestCase
  def test_something
    safe_assert_equal { [1, 2] }
  end
end

The additional syntax isn't drastically invasive; however, you are forcing additional syntax and requiring the understanding of why it's necessary.

Of course, in Java things would be even less expressive. The most likely solution would be to put the assertEquals in a Runnable, but I'd be interested in hearing other ideas. Regardless of the solution, it would obviously be invasive and take away from the readability of the test.

Being able to only say what is necessary is powerful. Stuart Halloway likes to talk about Essence and Ceremony, where Essence is the ability to say only what you want, and Ceremony is all the additional things you are required to say.

Macros seem to be a powerful tool for those looking to write Ceremony-free code.