Check position of the :Var and :var* keywords

Signal an error if the :Var or :var* keyword is found in any other
position than the first argument of a describe macro.  Fixes jorgenschaefer#223.

There are several issues with the :var(*) keywords, the most
important being it's inability to handle dynamic variables (jorgenschaefer#127).
But there is also the question of what the correct behaviour would be
if you use multiple :var(*) or when they are put anywhere but at the
beginning of the describe macro.

buttercup.el

@@ -863,7 +863,10 @@ mainly calls to `describe', `it' and `before-each'."
            `((let* ,(elt body 1)
                ,@(cddr body))))
           (t body))))
-    `(buttercup-describe ,description (lambda () ,@new-body))))
+    (if (or (memq :var new-body)
+              (memq :var* new-body))
+      `(error "buttercup: :var(*) found in invalid position of describe form \"%s\"" ,description)
+    `(buttercup-describe ,description (lambda () ,@new-body)))))
 
 (defun buttercup-describe (description body-function)
   "Function to handle a `describe' form.

docs/writing-tests.md

@@ -206,7 +206,9 @@ as full sentences in traditional
 
 The `describe` macro supports the optional `:var` and `:var*` args.
 These bind variables for the suite by passing them as a varlist to the
-`let` and `let*` form respectively.
+`let` and `let*` form respectively. Only one instance of `:var` or
+`:var*` is allowed, and it must come first in the `describe` form.  It
+can not be interspersed between `it` statements.
 
 ```Emacs-Lisp
 (describe "A spec using :VAR"

tests/test-buttercup.el

@@ -611,7 +611,16 @@ text properties using `ansi-color-apply'."
     (expect (macroexpand '(describe "description" :var* (foo bar) (+ foo bar)))
             :to-equal
             '(buttercup-describe "description"
-                                 (lambda () (let* (foo bar) (+ foo bar)))))))
+                                 (lambda () (let* (foo bar) (+ foo bar))))))
+  (describe "should error when "
+    (it ":var is not first"
+      (expect (macroexpand '(describe "description" (it "foo") :var (x)))
+              :to-equal
+              '(error "buttercup: :var(*) found in invalid position of describe form \"%s\"" "description")))
+    (it ":var* is not first"
+      (expect (macroexpand '(describe "description" (it "foo") :var* (x)))
+              :to-equal
+              '(error "buttercup: :var(*) found in invalid position of describe form \"%s\"" "description")))))
 
 (describe "The `buttercup-describe' function"
   (it "should run the enclosing body"